添加注释

README.md

@@ -1,8 +1,51 @@
 # Bilibili API JVM 调用库
 该项目提供 Bilibili API 的 JVM 调用, 协议来自 Bilibili Android APP 的逆向工程以及截包分析.
 
-# 重构
-使用 Kotlin 重构中...
+# 登录和登出
+登陆和登出均为异步方法, 需要在协程上下文中执行.
+
+    runBlocking {
+        BilibiliClient().run {
+            login(username, password)
+            logout()
+        }
+    }
+
+`login` 方法返回一个 `LoginResponse` 实例, 下次可以直接赋值到没有登陆的 `BilibiliClient` 实例中来恢复登陆状态.
+
+    BilibiliClient().apply {
+        this.loginResponse = loginResponse
+    }
+
+`LoginResponse` 继承 `Serializable`, 可被序列化.
+
+如果登录操作失败, 将抛出 `BilibiliApiException`(只要服务器返回的 code 不为 0 都将抛出异常), 通过以下代码获取服务器返回的 `code`
+
+    val code = bilibiliApiException.commonResponse.code
+
+在登陆操作中, 如果服务器返回 `-105` 表明本次登陆需要验证码(通常是由于多次错误的登陆尝试导致的), 原始返回如下所示
+
+    {"ts":1550569982,"code":-105,"data":{"url":"https://passport.bilibili.com/register/verification.html?success=1&gt=b6e5b7fad7ecd37f465838689732e788&challenge=9a67afa4d42ede71a93aeaaa54a4b6fe&ct=1&hash=105af2e7cc6ea829c4a95205f2371dc5"},"message":"验证码错误!"}
+
+自行访问 `data.url` 将打开一个极验弹窗, 通过验证码后再次调用登陆接口:
+
+    login(username, password, challenge, secCode, validate)
+
+`challenge` 为本次极验的唯一标识
+
+`validate` 为极验返回值
+
+`secCode` 为 `"$validate|jordan"`
+
+注意, `BilibiliClient` 不能严格保证线程安全, 如果在登出的同时进行登录操作可能引发错误.
+
+登陆后, 可以访问全部 API.
+
+# 主站
+//TODO
+
+# 直播站
+//TODO
 
 # License
 GPL V3

src/main/kotlin/com/hiczp/bilibili/api/BilibiliClient.kt

@@ -93,6 +93,9 @@ class BilibiliClient(
     /**
      * 登陆
      * v3 登陆接口会同时返回 cookies 和 token
+     * 如果要求验证码, 访问 data 中提供的 url 将打开一个弹窗, 里面会加载 js 并显示极验
+     * 极验会调用 https://api.geetest.com/ajax.php 上传滑动轨迹, 然后获得 validate 的值
+     * secCode 的值为 "$validate|jordan"
      *
      * @throws BilibiliApiException 用户名与密码不匹配(-629)或者需要验证码(极验)(-105)
      */

src/main/kotlin/com/hiczp/bilibili/api/passport/model/LoginResponse.kt

@@ -1,6 +1,7 @@
 package com.hiczp.bilibili.api.passport.model
 
 import com.google.gson.annotations.SerializedName
+import java.io.Serializable
 
 data class LoginResponse(
         @SerializedName("code")
@@ -11,7 +12,7 @@ data class LoginResponse(
         var `data`: Data,
         @SerializedName("ts")
         var ts: Long // 1550219689
-) {
+) : Serializable {
     data class Data(
             @SerializedName("cookie_info")
             var cookieInfo: CookieInfo,
@@ -21,13 +22,13 @@ data class LoginResponse(
             var status: Int, // 0
             @SerializedName("token_info")
             var tokenInfo: TokenInfo
-    ) {
+    ) : Serializable {
         data class CookieInfo(
                 @SerializedName("cookies")
                 var cookies: List<Cookie>,
                 @SerializedName("domains")
                 var domains: List<String>
-        ) {
+        ) : Serializable {
             data class Cookie(
                     @SerializedName("expires")
                     var expires: Int, // 1552811689
@@ -37,7 +38,7 @@ data class LoginResponse(
                     var name: String, // SESSDATA
                     @SerializedName("value")
                     var value: String // 5ff9ba24%2C1552811689%2C04ae9421
-            )
+            ) : Serializable
         }
 
         data class TokenInfo(
@@ -49,7 +50,7 @@ data class LoginResponse(
                 var mid: Int, // 20293030
                 @SerializedName("refresh_token")
                 var refreshToken: String // 6a333ebded3c3dbdde65d136b3190d21
-        )
+        ) : Serializable
     }
 
     //快捷方式