2. 需求分析与接口定义
低延迟评分接口的设计起点并非代码，而是对业务需求的精确梳理与接口契约的严格定义。本章将围绕四个核心环节展开：业务需求梳理、接口输入输出规范、RESTful 与 gRPC 的选型对比，以及 API 版本管理策略。这些决策将直接影响后续架构选型与性能基线。
2.1 业务需求梳理
在定义接口之前，必须明确评分系统的业务边界与核心指标。以下是从真实生产环境中提炼的关键需求清单：
| 需求维度 | 具体描述 | 优先级 |
|---|---|---|
| 功能需求 | 支持用户对商品/内容进行 1-5 分评分，支持评分后实时更新平均分与评分总数 | P0 |
| 性能需求 | P99 延迟 ≤ 50ms，吞吐量 ≥ 5000 QPS，支持突发流量 2x 峰值 | P0 |
| 一致性需求 | 最终一致性可接受，但同一用户重复提交需幂等去重 | P1 |
| 安全需求 | 接口需防刷、防重放，用户身份通过 Token 鉴权 | P1 |
| 可观测性 | 接口需暴露延迟、错误率、QPS 等核心指标至监控系统 | P2 |
实践提示： 需求优先级使用 P0/P1/P2 分级。P0 为必须满足，否则系统不可用；P1 为高优但可降级；P2 为锦上添花。在低延迟场景下，性能需求必须列为 P0。
2.2 接口输入输出规范
接口规范是前后端、上下游团队之间的契约。以下以“提交评分”和“查询评分”两个核心操作为例，定义标准化的请求与响应结构。
2.2.1 提交评分接口
POST /v1/ratings
Content-Type: application/json
Authorization: Bearer <token>
{
"target_id": "product_12345",
"target_type": "product",
"score": 4,
"user_id": "user_67890",
"idempotency_key": "req_abc123def456"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 0,
"message": "success",
"data": {
"rating_id": "rating_98765",
"average_score": 4.2,
"total_count": 128
},
"trace_id": "trace_00112233"
}2.2.2 查询评分聚合接口
GET /v1/ratings/summary?target_id=product_12345&target_type=product
Authorization: Bearer <token>HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 0,
"message": "success",
"data": {
"target_id": "product_12345",
"average_score": 4.2,
"total_count": 128,
"distribution": {
"1": 2,
"2": 5,
"3": 18,
"4": 55,
"5": 48
}
},
"trace_id": "trace_99887766"
}
规范要点：
- 统一响应结构：code + message + data + trace_id，便于客户端通用解析。
- 幂等键（idempotency_key）是低延迟去重的关键，服务端需基于该键做 24 小时内的幂等判断。
- 所有时间字段统一使用 Unix 毫秒时间戳，避免时区歧义。
2.3 RESTful vs gRPC 选型
对于低延迟评分接口，通信协议的选择直接影响延迟、吞吐与开发效率。以下从多个维度对比 RESTful（HTTP/1.1 + JSON）与 gRPC（HTTP/2 + Protobuf）：
| 对比维度 | RESTful (HTTP/1.1 + JSON) | gRPC (HTTP/2 + Protobuf) |
|---|---|---|
| 序列化效率 | JSON 文本格式，体积大，解析慢 | Protobuf 二进制格式，体积小，解析极快 |
| 传输延迟 | HTTP/1.1 队头阻塞，延迟较高 | HTTP/2 多路复用，延迟更低 |
| 吞吐量 | 中等，长连接支持有限 | 高，支持流式传输与双向流 |
| 开发效率 | 工具链成熟，调试直观 | 需定义 .proto 文件，调试需额外工具 |
| 浏览器兼容 | 原生支持 | 需 gRPC-Web 代理 |
| 适用场景 | 对外 API、浏览器端、简单 CRUD | 内部微服务、高吞吐、低延迟场景 |
选型结论： 对于本教程的评分接口，内部服务间通信推荐使用 gRPC 以获得最低延迟；对外暴露的 API 网关层仍可使用 RESTful 以兼容客户端。这种“内外有别”的混合架构在实践中最为常见。
2.4 API 版本管理策略
评分接口上线后必然面临迭代。版本管理不当会导致客户端兼容性灾难。以下是三种主流策略的对比：
| 策略 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
| URI 路径版本 | /v1/ratings → /v2/ratings |
直观、易于缓存、路由清晰 | URL 膨胀，语义耦合 |
| 请求头版本 | Accept: application/vnd.myapp.v1+json |
URL 干净，版本与资源解耦 | 调试不便，缓存策略复杂 |
| 查询参数版本 | /ratings?version=1 |
实现简单，兼容旧客户端 | 参数易被忽略，语义不明确 |
推荐策略： 对于低延迟评分接口，采用 URI 路径版本（如
/v1/ratings）。原因有三：一是路由匹配效率最高，无额外头部解析开销；二是 CDN 与网关层可直接基于路径做缓存与限流；三是团队协作时最直观，降低沟通成本。
2.5 本章小结
- 需求梳理：明确 P0 性能指标（P99 ≤ 50ms，5000 QPS），为后续架构设计设定硬约束。
- 接口规范：统一响应结构、幂等键、时间戳格式，减少沟通与调试成本。
- 协议选型：对外 RESTful，对内 gRPC，兼顾兼容性与性能。
- 版本管理：URI 路径版本 + 明确的废弃周期，保障接口平滑演进。