BV如何访问B站API:bili-api模块HTTP + gRPC双通道实现全解
BV如何访问B站API:bili-api模块HTTP + gRPC双通道实现全解
BV(哔哩哔哩第三方 Android 客户端)的 bili-api 模块 是整个应用与 B 站服务端通信的底座:它用一套统一的 HTTP 客户端工厂和一套 gRPC 通道工厂,把「Web 网页接口」与「App 移动端接口」两条数据通路封装在一起,上层功能只需用一个枚举参数就能自由切换。本文带你快速看懂这套 HTTP + gRPC 双通道架构的设计思路与关键实现。
为什么需要「双通道」?
B 站的数据接口历史上存在两套形态:
| 通道 | 协议 | 典型域名 | 数据格式 | 特点 |
|---|---|---|---|---|
| Web 通道 | HTTP/JSON | api.bilibili.com 等 |
JSON(BiliResponse<T>) |
接口开放度高、易调试,但风控更严 |
| App 通道 | gRPC/Protobuf | grpc.biliapi.net(443 端口) |
Protobuf 二进制 | 结构化强、体积小,官方 App 同款协议 |
BV 在 ApiType.kt 中用两个枚举值概括了这条分界线:
enum class ApiType {
Web, App
}
所有 Repository 请求方法都接受 preferApiType 参数,让调用方按需选择走哪条路。💡
模块结构一览:一个模块,四种角色
bili-api 的内部包结构与职责对应关系非常清晰:
http/— HTTP 通道:客户端工厂、各域名 API 对象、签名工具grpc/— gRPC 通道:proto 源文件 + 通道构建工具repositories/— 面向业务的 Repository 层,由 Koin 管理,双通道的「调度中心」entity/+http/entity/— 响应数据模型(Kotlinx Serialization)
依赖注入由 BiliApiModule.kt 声明,三行注解完成全部装配:
@Module
@Configuration
@ComponentScan
class BiliApiModule
@ComponentScan 会自动扫描本包下的 @Single 类(如 ChannelRepository、各业务 Repository),跨模块由 Koin 编译期插件发现,无需手写 single { } 注册代码。
HTTP 通道:一个工厂,构建全部客户端
BiliHttpClient:唯一的客户端构造入口
HTTP 通道的核心是 BiliHttpClient.kt。它不是「一个」客户端,而是一个带参数的工厂,每个业务域各自声明差异:
BiliHttpApi→api.bilibili.com,开启签名 + HTML 解析 + 2 次失败重试BiliLiveHttpApi→api.live.bilibili.com,只取直播间信息BiliPassportHttpApi→ 登录/验证码域BiliPlusHttpApi→www.biliplus.com(番剧辅助数据)BiliHttpProxyApi→ 用户自定义代理服务器,本地调试走127.0.0.1:8080
工厂的关键设计:所有客户端共享同一个 OkHttpClient 实例(连接池、线程池、BiliDns DNS 缓存全局只有一份),避免多个业务各占一套连接池。插件按需挂载:
fun create(
host: String? = null, // 默认域名;null 表示只用绝对 URL
addApiSign: Boolean = false, // 是否挂自动签名拦截器
addJsoup: Boolean = false, // 是否解析 HTML 响应
retryOnException: Int? = null, // 失败重试次数
detectAuthFailure: Boolean = true, // 会话失效自动登出
...
): HttpClient
JSON 反序列化也统一走 BiliHttpClient.json:coerceInputValues 容错字段类型漂移,ignoreUnknownKeys 容错 B 站新增字段——这两个配置是「第三方客户端不被服务端更新打挂」的关键。
自动签名:WBI 与 App 签名
B 站接口不是裸请求就能访问的,ApiSign.kt 实现了三种签名策略,由 encApiSign 拦截器 在每次发送前自动判断并附加:
- WBI 签名(
encWbi):针对/wbi/路径及番剧播放地址接口。从 nav 接口获取wbi_img_key/wbi_sub_key,按固定 64 位表重排混合出 mixin key,再对排序参数做 MD5 得到w_rid。key 每 2 小时自动刷新一次。 - App 签名(
encAppGet/encAppPost):针对带access_key参数或app.bilibili.com域名的请求。参数排序后拼接appkey与固定密钥做 MD5,附加sign参数——这是模仿官方 App 的鉴权方式。 - 指纹 Cookie 补全:Web 请求自动补
buvid3及buvid4/bili_ticket等指纹 Cookie(来自 WebCookieManager),保证指纹自洽,降低风控触发概率。
风控与失效兜底
HTTP 通道还有两道「保命」机制:
v_voucher风控识别:BiliHttpApi.checkForVVoucher 检查响应是否携带一次性风控凭证,触发时抛出VVoucherException,交由上层引导用户过极验验证;- 会话失效检测:AuthFailureDetection.kt 把「带凭证请求返回
-101」判定为登录态过期,回调 App 层自动登出,避免用户反复看到无效请求。
gRPC 通道:Protobuf + 元数据拦截器
proto 源文件与生成
gRPC 接口定义集中在 bili-api/grpc/proto/ 目录,按 B 站服务划分(app/playerunite、app/show/rank、community/service/dm 等)。构建时由 buildSrc 的 ProtobufConfiguration.usedProtoFiles 白名单控制哪些 proto 参与编译,自动生成本地 Kotlin gRPC 代码——所以源码树里看不到 *GrpcKt 类,它们在构建时生成。
generateChannel:通道工厂 + 五元组元数据
gRPC 通道的构建入口在 Channel.kt:
fun generateChannel(
accessKey: String,
buvid: String,
endPoint: String = BiliAppConf.GRPC_HOST, // grpc.biliapi.net
port: Int = BiliAppConf.GRPC_PORT, // 443
enableTransportSecurity: Boolean = true
): ManagedChannel
所有 gRPC 请求都经过一个 MetadataInterceptor,自动注入 B 站 App 协议的五个元数据头:
| 请求头 | 内容 | 来源 proto |
|---|---|---|
authorization |
identify_v1 <accessKey> |
字符串头 |
x-bili-metadata-bin |
accessKey、app 版本号、渠道、平台 | metadata.proto |
x-bili-device-bin |
appId、机型、build 号、buvid | device.proto |
x-bili-local-bin |
时区 | locale.proto |
x-bili-network-bin |
网络类型(Wi-Fi) | network.proto |
这些常量集中在 BiliAppConf.kt,模拟一台安卓官方 App 客户端的身份信息。通道复用协程的 Dispatchers.IO 作为执行器,与 Android 主线程解耦。
双通道如何切换:以获取播放地址为例
真正体现「双通道」价值的地方在 VideoPlayRepository.kt。以 getPlayData 为例,同一个「拿播放地址」需求,按 preferApiType 分叉:
ApiType.Web→ 调BiliHttpApi.getVideoPlayUrl,走fnval=4048的多格式 JSON 接口;ApiType.App→ 在 IO 线程上并发请求三种编码(H.264 / H.265 / AV1)的 gRPCplayViewUnite,合并结果后返回。
gRPC 侧的 Stub 都是懒加载的 CoroutineStub,并且用 runCatching 包裹:通道未初始化时静默降级为 null,由上层决定回退到 Web 通道。
通道生命周期由 ChannelRepository.kt 统一管理:
initDefaultChannel:登录后用accessKey + buvid初始化官方 gRPC 通道;initProxyChannel:支持用户填ip:port自建 gRPC 代理服务器(非 443 端口自动切换明文传输),方便自托管部署。
与 gRPC 配套的还有 HTTP 代理版:BiliHttpProxyApi.kt 把相同的番剧播放接口打到代理服务器上;而 generateGrpcProxyHeaders 则把 gRPC 那五元组元数据转成 Base64 HTTP 头,供代理转发 gRPC 请求时携带同等身份信息。
上手路线:读哪些文件最有价值
如果你想在 BV 基础上扩展新接口,建议按这个顺序阅读:
- BiliHttpClient.kt — 理解 HTTP 客户端如何组装插件
- ApiSign.kt — 理解 WBI / App 签名的触发条件
- Channel.kt — 理解 gRPC 元数据注入
- repositories/ 下任一 Repository — 看双通道如何被业务调用
- bili-api/example-response/live-event/ — 直播消息的 JSON5 样例,调试时对照响应结构很有用
新增 proto 时别忘了同步 ProtobufConfiguration.usedProtoFiles,否则新文件会被静默排除;bili-api 的单元测试是联网集成测试(如 BiliHttpApiTest.kt),需要在 local.properties 配好 test.sessdata、test.uid、test.buvid 才能跑通。
小结
BV 的 bili-api 模块用「两个工厂 + 一个枚举」把复杂的双协议世界收敛成简洁的接口:
- HTTP 工厂统一了客户端配置、签名、重试、风控检测,业务 API 对象只写 URL 和参数;
- gRPC 工厂统一了通道安全、执行器与 App 元数据,Stub 懒加载 + 优雅降级;
ApiType枚举让每条业务链路都能同时保留两条数据通路,单通道失败时可快速切换,这也是第三方客户端在 B 站频繁调整接口策略时保持稳定的关键设计。