BV如何访问B站API:bili-api模块HTTP + gRPC双通道实现全解

原创2026-10-29 19:52:341,743 阅读

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 拦截器 在每次发送前自动判断并附加:

  1. WBI 签名(encWbi):针对 /wbi/ 路径及番剧播放地址接口。从 nav 接口获取 wbi_img_key / wbi_sub_key,按固定 64 位表重排混合出 mixin key,再对排序参数做 MD5 得到 w_rid。key 每 2 小时自动刷新一次。
  2. App 签名(encAppGet / encAppPost):针对带 access_key 参数或 app.bilibili.com 域名的请求。参数排序后拼接 appkey 与固定密钥做 MD5,附加 sign 参数——这是模仿官方 App 的鉴权方式。
  3. 指纹 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)的 gRPC playViewUnite,合并结果后返回。

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 基础上扩展新接口,建议按这个顺序阅读:

  1. BiliHttpClient.kt — 理解 HTTP 客户端如何组装插件
  2. ApiSign.kt — 理解 WBI / App 签名的触发条件
  3. Channel.kt — 理解 gRPC 元数据注入
  4. repositories/ 下任一 Repository — 看双通道如何被业务调用
  5. 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 站频繁调整接口策略时保持稳定的关键设计。
登录后查看全文
bv