3.1 拿样本#

从应用商店渠道下载 APK，第一件事是记录指纹——样本即快照，App 后续更新导致接口变更时，可以按指纹回溯对比：

1
SHA256: 〔已脱敏〕
2
versionCode / versionName: 〔已脱敏〕
3
minSdk 24 / targetSdk 34
4
size: 355 MB

355MB 对于这个体量的 App 明显偏大，里面一定打包了重型资源（后面证实：内置词典数据库 + 游戏引擎 so）。

3.2 apktool 解包，先看 Manifest#

1
toolsapktool.cmd d -f apkbase.apk -o apktool_out

Manifest 里几个关键信息：

• 包名 com.vendor.vocab（已脱敏）

• 入口 SplashActivity / MainTabActivity，application 类 VAppApp

• 未见加固特征：没有 pairip / 360 / 腾讯乐固的壳，dex 可直接反编译

• 第三方 SDK 清单：微信/QQ 登录支付、友盟统计、个推、Bugly、数美（设备指纹）

• usesCleartextTraffic="true" + 自定义 network_security_config —— 调试遗留，说明客户端侧并没有认真做传输层加固

• 一个有意思的 deeplink scheme：vapp://com.vendor.vocab/word/lookup 等，全部 routing 映射到内部 Activity（后期做深链唤起有用，本次未深入）

3.3 从代码目录反推技术栈#

lib/arm64-v8a/ 下的 so 文件给出技术栈画像：

| so | 推断 |

| --- | --- |

| libcocos.so (45MB) | Cocos2d-x，承载内置的单词小游戏模块 |

| libmsaoaid*.so | 数美设备指纹 SDK（风控存在，但强度未知） |

| 没有 libflutter.so / libapp.so | 不是 Flutter，是原生 Kotlin/Java + Compose |

结论：不需要 blutter（Flutter 逆向工具），jadx 直接反编译 dex 即可。这一步的判断能省掉大量无效劳动。

3.4 顺手捡到的资产：内置词典库#

res/lexicon.db 有 18.5MB，拖出来是标准 SQLite：

1
$ sqlite3 lexicon.db ".tables"
2
dict_a_b  dict_main  dict_c  ... topic_book_map ...

1
dict_main: 52,012 条，字段 word / accent(音标) / mean_cn(释义) / freq(词频)
2
全部词表合计：约 10.9 万词条

topic_book_map（52,012 行）把单词映射到词书——这个 topic_id 后来被证明和服务端协议用的是同一套 ID 体系，先记住这个伏笔。

4.1 jadx 全量反编译，先挖域名#

1
toolsjadx-cli.cmd --no-res -j 4 -d jadx_out apkbase.apk

约 10MB 的 dex 反编译完（有 979 个 error，多为 Kotlin 元数据问题，不影响）。先 grep 域名常量，命中一个 Thrift 配置类，域名体系一览无余：

| 用途 | 域名（脱敏后） |

| --- | --- |

| 账号/认证 | passport.example.com |

| 学习服务 | learn.example.com |

| 学习 H5 | learn.example.com/{en,fr,ko,es}-mode/（App 内大部分学习页其实是 WebView） |

| 资源 | resource.example.com |

| 单词书 | booklist.example.com |

| 老 API | www.example.com/api/...?access_token= |

| CDN | cdn.example.com（图片/音频，相对路径直拼） |

4.2 命中要害：/rpc/* + thrift#

继续在反编译代码里搜路径常量，拿到这样一张表：

1
/rpc/users        /rpc/words       /rpc/studys
2
/rpc/user_study   /rpc/user_book   /rpc/resource_api
3
/rpc/unified_user_service ...

对应的 Java 包 com.vendor.online.* 下的类，全是 Apache Thrift 生成的桩代码（识别特征：*_args / *_result 内部类、StandardScheme、writeFieldBegin(new TField(...))）。也就是说：

服务端接口用的是 Thrift over HTTP，而且客户端里带着完整的接口契约。

这是本次分析最大的成本变量：Thrift 生成代码是“自描述”的——每个方法名、每个结构体的 field id 和类型都以字面量形式存在。不需要抓一个包，协议就还原了 90%。

4.3 还原传输层#

三个关键类的信息拼出完整传输模型：

1. URL 模板（thrift/a.java）："%s%s/%s/%d" → POST https://learn.example.com/rpc/user_study/{method}/{当前毫秒时间戳}

2. 消息格式（thrift/k.java）：

   1
   okhttp3.l.a aVarA = new okhttp3.l.a()
   2
    .a("Accept", "application/x-thrift")
   3
    .a("User-Agent", "vapp_app/android/" + version)
   4
    .a("Cookie", strA);   // ← Cookie 里带凭证
   

3. 凭证载体（另一处请求封装实锤）：

   1
   map.put("Cookie", "access_token=" + userRecordQ.getToken());
   

鉴权模型结论：所有业务请求只需要一个 HTTP 头 Cookie: access_token=<token>。没有签名、没有 pinning、没有时间戳校验。防护等级一目了然。

4.4 从生成代码提取 IDL#

以最核心的学习进度上报为例，生成代码里的 write() 方法直接给出字段表：

1
oprot.writeFieldBegin(new TField("word_topic_id", TType.I64, (short) 1));
2
oprot.writeFieldBegin(new TField("current_score", TType.I32, (short) 2));
3
oprot.writeFieldBegin(new TField("span_days", TType.I32, (short) 3));
4
...

翻译成 IDL：

1
struct UserDoneWordRecord {
2
  1:  i32 word_topic_id        8:  i32 tag_id
3
  2:  i32 current_score        9:  i32 spell_score
4
  3:  i32 span_days           10:  i32 listening_score
5
  4:  i32 used_time           11:  i32 chn_score
6
  5:  i32 done_times          12:  i32 review_round
7
  6:  i32 wrong_times
8
  7:  i32 is_first_do_at_today
9
}
10

11
service UserStudyApiService {
12
  i32 update_done_data(1: i64 last_sync_at,
13
                       2: list<UserDoneWordRecord> arr_done_records,
14
                       3: i32 current_word_level_id,
15
                       4: bool is_today_completed);
16
  UserBasicInfoPlusV2 user_basic_info_v2();
17
  list<UserLearnedWordInfo> get_learned_words_list(1: i32 book_id);
18
  list<UserRoadMapElementV2> roadmap_by_word_level_v2(1: i32 book_id);
19
  list<SelectBookPlanInfo> get_all_selected_book_plan_info();
20
  ...
21
}

服务与 host 的映射也一并确认：user_study → learn / resource_api → resource / unified_user_service → passport，且每个都有国际站备份域名。

到这一步，协议还原的情报工作已经完成，剩下的全部是工程问题。

5.1 规则速查#

Compact Protocol 的核心规则（对照实现看最直观）：

1. varint：每个字节 7 bit 有效位，MSB=1 表示后续还有字节

2. zigzag：有符号整数先 zigzag 再 varint。zigzag32(n) = (n<<1) ^ (n>>31)

3. struct：字段序列，每个字段头 1 字节 (delta<<4)|type，delta = fid - last_fid；delta ≤ 0 或 > 15 时写成 type 字节 + zigzag varint 的 fid；struct 以 0x00(STOP) 结束

4. bool：在 struct 内直接编码进 type nibble（1=true，2=false），不占 value 字节

5. list：1 字节 (size<<4)|elem_type；size ≥ 15 时用 0xF0|elem_type + varint size

6. double：小端 8 字节

7. binary/string：varint 长度 + 原始字节

5.2 核心实现（Python，零依赖）#

先写 primitives：

1
def _uvarint(n: int) -> bytes:
2
    out = bytearray()
3
    while True:
4
        b = n & 0x7F
5
        n >>= 7
6
        if n:
7
            out.append(b | 0x80)
8
        else:
9
            out.append(b)
10
            return bytes(out)
11

12
def _zigzag32(n): return ((n << 1) ^ (n >> 31)) & 0xFFFFFFFF
13
def _zigzag64(n): return ((n << 1) ^ (n >> 63)) & 0xFFFFFFFFFFFFFFFF

消息头 + framed 传输：

1
# 一条 CALL 消息 = [0x82][0x21][varint seqid][string method][args...]
2
# 外层 framed：4 字节大端长度前缀
3
w = Writer()
4
w.byte(0x82)                # protocol id
5
w.byte((1 << 5) | 1)        # version 1 | CALL(1) << 5
6
w.varint(1)                 # seqid
7
w.string('user_basic_info_v2')
8
frame = w.raw()
9
body = struct.pack('>I', len(frame)) + frame

发起调用（注意这里做了代理环境 TLS 抖动的自动重试，第 10 节会展开）：

1
POST https://learn.example.com/rpc/user_study/user_basic_info_v2/{ms}
2
Accept: application/x-thrift
3
Cookie: access_token=<token>
4
User-Agent: vapp_app/android/<version> os_version/<os-version>

响应解析：剥 framed 头 → 校验 0x82 → 读 (type<<5)|version（REPLY=2）→ seqid → method name → 进入 result struct。result struct 的约定是：

• field 0 = success

• field 1 = SystemException{1: from_service, 2: from_method, 3: code, 4: message}

• field 2 = LogicException{同上}

5.3 写的时候踩的最大的坑：list header#

我第一版把 list header 写成了“varint(size) + byte(type)”——这是从 Thrift 的非 compact 协议记忆里带过来的错误。实际 compact 是单字节 (size<<4)|elem_type：

1
# ❌ 错误版（第一次实现）
2
self.varint(len(items)); self.byte(elem_ct)
3

4
# ✅ 正确版
5
n = len(items)
6
if n < 15:
7
    self.byte((n << 4) | elem_ct)
8
else:
9
    self.byte(0xF0 | elem_ct)
10
    self.varint(n)

这个 bug 的表现非常隐蔽：所有不携带 list 的接口（比如只读用户信息）一切正常，直到第一次解析带 list 的响应才炸——cannot skip ct=20（非法的 compact type）。

调试过程值得一提：我先用“逐字段打印”定位到是 list header 错位，再对照协议规范重写。这类“协议魔数错位”问题的通用排查法：

1. 把响应原始 hex dump 出来

2. 和预期字段逐个字节比对

3. 找到第一处语义不合法的字节（本例中是 type nibble=20，合法值只有 0-12）

修复后一条命令直接跑通——这也是自己的协议栈相对黑盒抓包的最大优势：任何一个字节的偏差都有明确的责任人。

5.4 通用结构解析器#

为了不用给上百个结构体逐个写解析代码，再加一个“泛型解析”：struct → {field_id: value} 的嵌套 dict，遇到未知字段按类型跳过：

1
def generic(self, ct):
2
    if ct == CT_TRUE:  return True
3
    if ct == CT_FALSE: return False
4
    if ct == CT_I32:   return self.zigzag(32)
5
    if ct == CT_BINARY:
6
        b = self.binary()
7
        return b.decode('utf-8', 'replace')   # 尽力还原文本
8
    if ct == CT_STRUCT:
9
        out = {}
10
        self.struct(lambda fid, ct: out.__setitem__(fid, self.generic(ct)) or True)
11
        return out
12
    if ct in (CT_LIST, CT_SET):
13
        n, ect = self.list_header()
14
        if n == 0: return []
15
        return [self.generic(ect) for _ in range(n)]
16
    ...

这一个函数后面承载了所有 detail 类接口的解析，字段 id 语义在上层按需解释。

8.1 用户与词书#

1
user_basic_info_v2()

返回（脱敏后）：

1
{
2
  "user_info": {
3
    "current_word_level_id": 13,
4
    "current_word_level_name": "脱敏-当前词书",
5
    "nickname": "***",
6
    "avatar": "https://cdn.example.com/ugc/.../avatar.jpg"
7
  },
8
  "learn_info": {
9
    "last_sync_done_score_time": 1729603842,
10
    "daily_plan_count": 200,
11
    "review_plan_count": 800
12
  }
13
}

三个关键数字：正在学习的词书（word_level_id=13）、每日新学 200、每日复习 800。

8.2 学习计划与“今天学什么”#

1
get_all_selected_book_plan_info()   # → 12 本在学的书及各自计划
2
roadmap_by_word_level_v2(13)       # → 6,279 个 topic
3
get_learned_words_list(13)         # → 2,665 条已学记录

研究的核心结论（这也解释了为什么“网页版背单词”在架构上是可行的）：

服务端不下发“今天该学哪些词”。它只给学习计划、roadmap（全部词条）和已学记录；“未学 / 今日新学 / 待复习 / 已掌握”四个分组完全由客户端本地计算：

1
record == null 或 score == -1024  → unlearned
2
todayNew == true                   → todayLearned
3
!todayNew 且 score ∈ [0,4]         → unreviewed（待复习）
4
score > 4                          → reviewed（已掌握）

这意味着：网页端可以完全本地驱动学习流程 UI，只在答题后把结果批量上报——和 App 的行为模型一致。上报就是 update_done_data，我把它证明是安全的之后才接进页面。

8.3 单词详情#

1
get_topic_resource_v2(TopicKey{topic_id, word_level_id, tag_id},
2
                      channel=STUDY, with_dict=True, with_media=True)

一个词的结构（脱敏样本，public 一词）：

1
{
2
  "word_basic_info": {
3
    "topic_id": 17234,
4
    "word": "public",
5
    "accent_us": "/ˈpʌblɪk/",  "accent_uk": "/ˈpʌblɪk/",
6
    "audio_us": "/r/us_public_20231101...mp3",
7
    "audio_uk": "/r/uk_public_20220421...mp3",
8
    "mnemonic": "publ人民 + ic...的 → public 公开的，公众的"
9
  },
10
  "chn_means": [{"type": "adj.", "mean": "公用的，公共的"}, "..."],
11
  "sentences": [{"en": "There is a non-smoking sign in the public place.",
12
                 "cn": "公共场所有一块禁烟标志。",
13
                 "img": "/r/1691006137...jpeg", "audio": "/r/um2tz....mp3"}]
14
}

其中音视频都是相对路径，前端拼 https://cdn.example.com 直连即可（实测无防盗链、200）。

词库侧：App 自带的 lexicon.db（10.9 万词，第 3.4 节）提供了 topic_id ↔ 单词的本地索引，与服务端 topic_id 同体系，可用于离线补全与查询。

10.1 慢：链路本身 3 秒/次#

实测单条 thrift 调用 3 秒，PowerShell 发同样的请求甚至 18 秒。定位后发现不是协议问题：thrift 响应头是 Connection: keep-alive，但代理环境下 TLS 握手反复重建，纯链路成本。

解法一套组合拳：

服务端内存缓存 + stale-while-revalidate

1
def cached(key, ttl, fn, stale=0):
2
 # fresh 命中：直接返回
3
 # fresh 过期但 stale 期内：立即返回旧值 + 后台线程刷新
4
 # 全过期：阻塞刷新（预热保证此路径极少走到）

用户信息/词书计划 fresh 60s + stale 900s；词详情 24h 缓存（内容几乎不变）。

写后精确失效：上报成功立刻清除 learned/queues 缓存，不靠自然过期

批量 + 并行：/api/words?ids=a,b,c 一次请求，线程池 10 worker 并行拉 N 个词详情，前端一次预取下一批 8 个

后台预热：服务启动/登录后，daemon 线程自动把 plan → queues → 前 64 个词灌进缓存。用户输短信验证码的几十秒正好被利用

最终效果（预热完成后）：

1
plan     3ms     queues  28ms     words×8  9ms

10.2 稳：代理环境 TLS 抖动#

TUN + fakeip 模式下 SSL EOF 偶发（同一域名反复成功又反复 reset）。客户端加定向重试：仅对 SSL/EOF/handshake 类错误指数退避重试，最多 3 次，其他错误直接抛。

10.3 数据不丢#

答题记录按 App 同款模型落 localStorage（syncing 队列语义），每次变更即持久化、页面隐藏/关闭时 checkpoint；同词多条记录合并上报（后者覆盖前者，与队列去重一致）。

10.4 一个教训：数字 key 的 JSON 陷阱#

thrift 泛型解析产出 {2: {...}, 4: {...}}（field id 为 int key），直接 json.dumps 后 field id 变字符串，前端 ui[2] 全部 undefined——整个页面空白且无报错。修复：在后端加一层适配，把字段 id 翻译成可读字段再输出：

1
return {
2
    'word': w.get(2), 'accent_uk': w.get(4), 'accent_us': w.get(3),
3
    'audio_us': w.get(5), 'audio_uk': w.get(6),
4
    'means': [{'type': m.get(3), 'mean': m.get(4)} for m in d.get(2, [])],
5
    'sentences': [{'en': s.get(4), 'cn': s.get(5), 'img': s.get(7), 'audio': s.get(8)}
6
                  for s in d.get(4, [])],
7
    ...
8
}

这类“协议层 ID 语义”和“表现层字段语义”的撕裂，是所有做协议适配的前端/后端都会踩的坑，值得早早在架构里隔一层。