Skip to content

0 Get Started

Jump to bottom
jfeng edited this page Apr 9, 2020 · 22 revisions

平台与 SDK 对应关系

LeanCloud Java SDK 主要包含以下几个 library，其层次结构以及平台对应关系如下：

基础包（可以在纯 Java 环境下调用）

  • storage-core：包含所有数据存储的功能，如
    • 结构化数据（AVObject）
    • 内建账户系统（AVUser）
    • 查询（AVQuery）
    • 文件存储（AVFile）
    • 社交关系（用户 follow 关系）
    • 朋友圈（AVStatus）
    • 短信（AVSMS）
    • 等等
  • realtime-core：部分依赖 storage-core library，实现了 LiveQuery 以及即时通讯功能，如：
    • LiveQuery
    • AVIMClient
    • AVIMConversation 以及多种场景对话
    • AVIMMessage 以及多种子类化的多媒体消息
    • 等等

云引擎使用的包

  • engine-core：是 LeanCloud 云引擎项目需要依赖的包。

Android 特有的包

  • storage-android：是 storage-core 在 Android 平台的定制化实现，接口与 storage-core 完全相同。
  • realtime-android：是 realtime-core 在 Android 平台的定制化实现，并且增加 Android 推送相关接口。
  • mixpush-android：是 LeanCloud 混合推送的 library，支持华为、小米、魅族、OPPO、VIVO 的官方推送。
  • leancloud-fcm：是 Firebase Cloud Messaging 的封装 library，供国际版 app 使用推送服务。

模块依赖关系

Java SDK 一共包含如下几个模块：

目录 模块名 适用平台 依赖关系
./core storage-core，存储核心 library java 无，它是 LeanCloud 最核心的 library
./realtime realtime-core，LiveQuery 与实时通讯核心 library java storage-core
./leanengine engine-core，云引擎 library java storage-core
./android-sdk/storage-android storage-android，Android 存储 library Android storage-core
./android-sdk/realtime-android realtime-android，Android 推送、LiveQuery、即时通讯 library Android storage-android, realtime-core
./android-sdk/mixpush-android Android 混合推送 library Android realtime-android
./android-sdk/leancloud-fcm Firebase Cloud Messaging library Android realtime-android

获取 SDK

获取 SDK 有多种方式，较为推荐的方式是通过包依赖管理工具下载最新版本。

包依赖管理工具安装

  • 纯 Java 环境下运行的库（storage-core, realtime-core, engine-core）已经发布到 maven central repo。
  • Android 平台使用的库（storage-android, realtime-android, mixpush-android, leancloud-fcm）也已经发布到 maven central repo。

开发者可以从线上直接获取。

使用存储功能

Example for Maven：

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>storage-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

and for Ivy:

<dependency org="cn.leancloud" name="storage-core" rev="{currentVersion}" />

and for SBT:

libraryDependencies += "cn.leancloud" %% "storage-core" % "{currentVersion}"

and for Gradle:

implementation 'cn.leancloud:storage-android:{currentVersion}'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'

请注意：{currentVersion} 指当前最新版本，可以从maven central repository查询获得。

使用即时通讯 / 推送服务

Example for Maven：

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>realtime-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

and for Ivy:

<dependency org="cn.leancloud" name="realtime-core" rev="{currentVersion}" />

and for SBT:

libraryDependencies += "cn.leancloud" %% "realtime-core" % "{currentVersion}"

and for Gradle:

    implementation 'cn.leancloud:realtime-android:{currentVersion}'
    implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'

请注意：{currentVersion} 指当前最新版本，可以从maven central repository查询获得。

使用混合推送服务

Example for Gradle：

implementation 'cn.leancloud:mixpush-android:{currentVersion}'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'

请注意：{currentVersion} 指当前最新版本，可以从maven central repository查询获得。

云引擎项目

Example for Maven：

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>engine-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

请注意：{currentVersion} 指当前最新版本，可以从maven central repository查询获得。

手动安装

从源码编译

To check out and build the LeanCloud Java SDK source, issue the following commands:

$ git clone [email protected]:leancloud/java-sdk-all.git
$ cd java-sdk-all/
$ mvn clean install

To build Android SDK source, issue the following commands:

$ cd java-sdk-all/
$ cd android-sdk/
$ gradle clean assemble

初始化

假设已经设置好了 SDK 依赖关系，可以开始功能接入了，我们首先看一下如何进行 SDK 的初始化。

获取 appId 与 appKey

首先进入 控制台 > 设置 > 应用 Key 来获取 App ID 以及 App Key。

Java 平台初始化代码

在程序执行之初，执行如下代码即可完成初始化：

AVOSCloud.initialize("{your_appId}","{your_appKey}");

将上述代码中的 App ID 以及 App Key 替换成从控制台复制粘贴的对应的数据即可。

云引擎项目初始化

在 ServletContextListener 子类的 contextInitialized 方法中，按照如下流程进行初始化：

@Override
public void contextInitialized(ServletContextEvent arg0) {
  // 注册子类化
  AVObject.registerSubclass(Todo.class);

  // 可选步骤，设置访问云引擎实例的开发版标志
  if ("development".equals(appEnv) && "true".equals(haveStaging) || "stage".equals(appEnv)) {
    AVCloud.setProductionMode(false);
  }
  // 初始化AVOSCloud，请保证在整个项目中间只初始化一次
  LeanEngine.initialize(”{your_appId}“, ”{your_appKey}“, ”{your_appMasterKey}“);
  // 在请求签名中使用masterKey以激活云代码的最高权限
  RequestSignImplementation.setMasterKey(”{your_appMasterKey}“);
  // 向云引擎注册云函数
  LeanEngine.register(Cloud.class);
}

Android 平台初始化

在 Application 类的 onCreate 函数中，加入如下代码：

import cn.leancloud.AVOSCloud;

public class MyLeanCloudApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // 初始化参数依次为 this, AppId, AppKey
        // 注意这里千万不要调用 cn.leancloud.core.AVOSCloud 的 initialize 方法，否则会出现 NetworkOnMainThread 等错误。
        AVOSCloud.initialize(this,"{your_appId}}","{your_appKey}");
    }
}

然后打开 AndroidManifest.xml 文件来配置 SDK 所需要的手机的访问权限以及声明刚才我们创建的 MyLeanCloudApp 类：

<!-- 基础模块（必须加入以下声明）START -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 基础模块 END -->

<application
  ...
  android:name=".MyLeanCloudApp" >

  <!-- 实时通信模块、推送（均需要加入以下声明） START -->
  <!-- 实时通信模块、推送都要使用 PushService -->
  <service android:name="com.avos.avoscloud.PushService"/>
  <receiver android:name="com.avos.avoscloud.AVBroadcastReceiver">
    <intent-filter>
      <action android:name="android.intent.action.BOOT_COMPLETED"/>
      <action android:name="android.intent.action.USER_PRESENT"/>
      <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
  </receiver>
  <!-- 实时通信模块、推送 END -->

  <!-- 反馈组件（需要加入以下声明）START -->
  <activity
     android:name="com.avos.avoscloud.feedback.ThreadActivity" >
  </activity>
  <!-- 反馈组件 END -->
</application>

开启调试日志

在应用开发阶段，你可以选择开启 SDK 的调试日志（debug log）来方便追踪问题。调试日志开启后，SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口，或是浏览器 Console 或是 LeanCloud 控制台的 云引擎日志 中。

// 在 AVOSCloud.initialize 之前调用
AVOSCloud.setLogLevel(AVLogger.Level.DEBUG);// or AVOSCloud.setLogLevel(AVLogger.Level.VERBOSE);

指定服务节点

SDK 的初始化方法默认使用中国华北节点，如需切换到 其他可用节点，请参考如下用法：

// 在 AVOSCloud.initialize 之前调用
// 可选的节点有：
//    REGION.NorthChina - 华北节点，默认节点
//    REGION.EastChina  - 华东节点
//    REGION.NorthAmerica - 北美节点
AVOSCloud.setRegion(AVOSCloud.REGION.NorthChina);

同步/异步调用

新版本 SDK 主要提供两类接口，接口签名对 Java 和 Android 平台的接口来说都是一样的，一般而言：

  1. xxxInBackground（例如 saveInBackground/findInBackground/deleteInBackground） 是异步接口，统一会返回 Observable 实例，后续需要调用 RxJava 的 subscribe/consumer 等方法来处理实际执行结果。
  2. xxx 是同步接口（AVUser#logIn 除外），会直接返回操作的结果（或者为空）。

注意：xxxInBackground 系列接口在 Java 平台会自动变为同步接口（即同样的函数在 Android 平台调用是异步的，但是在 Java 平台调用是同步的）。

Android SDK 老版本迁移

如果你已经在使用我们老版本 Android SDK，要迁移到当前新版本，函数接口方面新版 SDK 尽可能沿用老版 SDK 的命名方式，所以要做的改动主要是Callback 回调机制的修改。

Observable 接口

例如老的方式保存一个 AVObject 的代码如下(Callback 方式)：

final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议，周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码，服务端就会自动添加这个字段
todo.saveInBackground(new SaveCallback() {
  @Override
  public void done(AVException e) {
    if (e == null) {
      // 存储成功
      Log.d(TAG, todo.getObjectId());// 保存成功之后，objectId 会自动从服务端加载到本地
    } else {
      // 失败的话，请检查网络环境以及 SDK 配置是否正确
    }
  }
});

而新版本 SDK 里 AVObject#saveInBackground 方法，返回的是一个 Observable<? extends AVObject> 实例，我们需要 subscribe 才能得到结果通知，新版本的实现方式如下：

final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议，周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码，服务端就会自动添加这个字段
todo.saveInBackground().subscribe(new Observer<AVObject>() {
  public void onSubscribe(Disposable disposable) {
  }
  public void onNext(AVObject avObject) {
    System.out.println("remove field finished.");
  }
  public void onError(Throwable throwable) {
  }
  public void onComplete() {
  }
});

ObserverBuilder 工具类

这个改动比较大，考虑到尽量降低迁移成本，我们准备了一个工具类 cn.leancloud.convertor.ObserverBuilder，该类有一系列的 buildSingleObserver 方法，来帮我们由原来的 Callback 回调函数生成 Observable 实例，上面的例子按照这种方法可以变为：

final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议，周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码，服务端就会自动添加这个字段
todo.saveInBackground().subscribe(ObserverBuilder.buildSingleObserver(new SaveCallback() {
  @Override
  public void done(AVException e) {
    if (e == null) {
      // 存储成功
      Log.d(TAG, todo.getObjectId());// 保存成功之后，objectId 会自动从服务端加载到本地
    } else {
      // 失败的话，请检查网络环境以及 SDK 配置是否正确
    }
  }
}));

处理异步调用结果的两种方式，可供大家自由选择。

另外，在新版 SDK 中我们统一将包名的 root 目录由 com.avos.avoscloud 改成了 cn.leancloud，也需要大家做一个全局替换。

Clone this wiki locally