深念

Appearance

MyBilibili API 规范（v1.0）

🕒 Published at:

MyBilibili API 规范（v1.0） ​

1. 规范目标 ​

  1. 统一所有服务的 API 风格，便于 gRPC 改造和跨端调用
  2. 定义清晰的错误码体系
  3. 规范认证、分页、幂等
  4. 为网关（gateway）统一接入做准备

2. 通用约定 ​

2.1 协议 ​

  • 对外：HTTPS（网关入口）
  • 服务间：gRPC（ProtoBuf）
  • 浏览器端：WebSocket（realtime）

2.2 数据格式 ​

  • 请求/响应：JSON
  • 时间：Unix 毫秒时间戳（number）
  • ID：long/int64
  • 文本：UTF-8

2.3 统一响应结构 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {},
  "requestId": "req-xxxx"
}
字段类型说明
codeint0 成功，非 0 失败（见错误码）
messagestring提示信息
dataobject业务数据
requestIdstring链路追踪 ID

2.4 分页 ​

json
// 请求
GET /api/v1/videos?page=1&pageSize=20

// 响应
{
  "code": 0,
  "data": {
    "list": [],
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "hasMore": true
  }
}
参数默认上限
page1-
pageSize20100

2.5 认证 ​

请求头：

Authorization: Bearer <jwt_token>

流程：

  • 登录/注册 → 返回 accessToken（JWT，有效期 7 天）+ refreshToken（30 天）
  • 访问受保护接口带 Authorization
  • 网关校验 JWT + Redis 会话
  • 登出 → 服务端失效会话

2.6 幂等 ​

写操作支持幂等（防止重复提交）：

Idempotency-Key: <client generated uuid>
  • 服务端对同一 key 只处理一次
  • 用于：下单、支付、发布稿件

3. 错误码体系 ​

3.1 全局错误码（0-999） ​

code说明
0成功
400参数错误
401未认证/登录过期
403无权限
404资源不存在
405方法不允许
409冲突（重复提交）
429请求过于频繁（限流）
500服务器内部错误
503服务不可用

3.2 业务错误码（1000+） ​

用户模块（1000-1099）：

code说明
1001用户名已存在
1002手机号/邮箱已注册
1003验证码错误
1004验证码过期
1005密码错误
1006账号被锁定（15 分钟）
1007账号被禁用

内容模块（1100-1199）：

code说明
1101稿件不存在
1102稿件审核中
1103稿件被拒绝
1104分区不存在
1105标签超限

互动模块（1200-1299）：

code说明
1201评论包含违禁词
1202评论频率过快
1203已点赞，不能重复
1204已收藏，不能重复

订单模块（1300-1399）：

code说明
1301商品不存在
1302库存不足
1303订单不存在
1304订单状态不允许此操作
1305支付失败

通用业务错误（1900-1999）：

code说明
1901数据不存在
1902数据已存在
1903操作过于频繁
1904服务暂不可用

4. 接口分类 ​

4.1 认证接口（网关） ​

方法路径说明
POST/api/v1/auth/register注册（邮箱/手机验证码）
POST/api/v1/auth/login登录
POST/api/v1/auth/refresh刷新 token
POST/api/v1/auth/logout登出
POST/api/v1/auth/forgot-password找回密码

4.2 用户接口 ​

方法路径说明
GET/api/v1/users/用户信息
PUT/api/v1/users/更新资料
PUT/api/v1/users/{id}/avatar上传头像
GET/api/v1/users/{id}/follows关注列表
GET/api/v1/users/{id}/fans粉丝列表
POST/api/v1/users/{id}/follow关注

4.3 视频/稿件接口 ​

方法路径说明
POST/api/v1/videos发布稿件
GET/api/v1/videos/稿件详情
PUT/api/v1/videos/更新稿件
DELETE/api/v1/videos/删除稿件
GET/api/v1/videos分页列表（分区/关键词）
POST/api/v1/videos/{id}/play播放（计播放量）

4.4 互动接口 ​

方法路径说明
POST/api/v1/videos/{id}/like点赞
DELETE/api/v1/videos/{id}/like取消点赞
POST/api/v1/videos/{id}/favorite收藏
GET/api/v1/videos/{id}/comments评论列表
POST/api/v1/videos/{id}/comments发评论
DELETE/api/v1/comments/删评论
POST/api/v1/videos/{id}/share分享（计数）

4.5 弹幕/实时（WebSocket） ​

WS /ws?token=<jwt>&roomId=<videoId>
消息类型说明
danmaku.send发弹幕
danmaku.list弹幕列表
live.join/leave直播间进出
live.gift送礼
notify.message消息通知

4.6 搜索接口 ​

方法路径说明
GET/api/v1/search/videos搜索视频
GET/api/v1/search/users搜索用户
GET/api/v1/hot/rank热榜
GET/api/v1/recommend/videos推荐列表

4.7 转码/媒体（异步） ​

方法路径说明
POST/api/v1/media/transcode提交转码任务
GET/api/v1/media/tasks/查询转码进度
POST/api/v1/media/ai/subtitleAI 字幕
POST/api/v1/media/ai/summaryAI 总结
GET/api/v1/media/streams/获取播放地址（HLS）

4.8 广告接口 ​

方法路径说明
GET/api/v1/ads/display获取广告位
POST/api/v1/ads/impression展示上报
POST/api/v1/ads/click点击上报

4.9 商城/订单接口 ​

方法路径说明
GET/api/v1/products商品列表
POST/api/v1/orders创建订单
GET/api/v1/orders/订单详情
POST/api/v1/orders/{id}/pay支付
POST/api/v1/orders/{id}/refund退款

4.10 管理接口（admin） ​

方法路径说明
POST/api/v1/admin/videos/{id}/review审核稿件
GET/api/v1/admin/users用户管理
PUT/api/v1/admin/users/{id}/status禁/解禁
GET/api/v1/admin/comments评论管理
GET/api/v1/admin/stats数据统计
GET/api/v1/admin/login-logs登录日志

5. gRPC 服务定义（服务间） ​

proto
syntax = "proto3";

package mybilibili.core;

// 用户服务
service UserService {
    rpc GetUser(GetUserRequest) returns (User);
    rpc UpdateUser(UpdateUserRequest) returns (User);
    rpc GetUserFollows(PageRequest) returns (UserPage);
}

// 内容服务
service VideoService {
    rpc GetVideo(GetVideoRequest) returns (Video);
    rpc ListVideos(PageRequest) returns (VideoPage);
    rpc PublishVideo(Video) returns (Video);
}

// 互动服务
service InteractionService {
    rpc Like(LikeRequest) returns (Empty);
    rpc Comment(CommentRequest) returns (Comment);
    rpc Favorite(FavoriteRequest) returns (Empty);
}

服务发现命名：

  • service://core/UserService.GetUser
  • service://media/VideoService.GetVideo

6. 网关路由映射 ​

/api/v1/users/*        → core
/api/v1/videos/*       → core
/api/v1/comments/*     → core
/api/v1/search/*       → search
/api/v1/hot/*          → search
/api/v1/media/*        → media
/api/v1/ads/*          → ads
/api/v1/products/*     → store
/api/v1/orders/*       → store
/ws                    → realtime
/api/v1/admin/*        → admin（独立鉴权）

7. 版本兼容 ​

  • URL 带版本：/api/v1/
  • 破坏性变更 → 升级 v2，v1 保留过渡期
  • 服务间 gRPC：proto 向后兼容（新增字段，不删不改）

8. 日志与追踪 ​

  • 每个请求带 requestId（网关生成，穿透到服务）
  • 服务间传递：gRPC metadata
  • 日志结构化：{requestId, service, method, latency, code}
  • 出错可全链路串联排查