4. API基础概念
保险定价与实时报价服务，本质上是一个“请求—计算—返回”的数据交换系统。前端渠道（官网、App、代理人展业工具、第三方比价平台）需要把投保人信息、标的物信息、保障方案等参数传给定价引擎，定价引擎再返回保费、费率因子、折扣、承保条件等结果。这个过程中，API 协议的选择直接决定了报价的延迟、吞吐、可维护性和扩展能力。本节不讨论具体业务规则，而是从协议层面建立判断框架，帮助你在不同报价场景中做出合理的技术选型。
核心原理：四种协议的通信模型差异
RESTful API 基于 HTTP 语义，用 URL 定位资源、用方法表达操作，通常以 JSON 传输。它的核心优势是通用、易调试、生态成熟，几乎任何语言和网关都能直接支持。在保险报价中，REST 适合“一次请求返回一个完整报价结果”的同步场景，例如车险标准报价、意外险保费试算。
GraphQL 的核心是“客户端声明需要哪些字段”。它通过单一端点接收查询语句，由服务端按字段解析并返回精确结构。对于报价场景，当不同渠道需要的字段差异很大——有的只要总保费，有的要完整费率因子明细，有的还要附加险逐项价格——GraphQL 能避免过度获取和多次请求。
gRPC 基于 HTTP/2 和 Protobuf，采用二进制序列化，支持四种流式模式。它的强项是高性能、强类型契约和跨语言代码生成。在保险核心系统中，定价引擎往往被多个内部服务高频调用，gRPC 能显著降低序列化开销和网络延迟，适合“报价服务到定价引擎”的内部链路。
WebSocket 提供全双工长连接，服务端可以主动推送消息。保险报价中，它适合需要实时更新或多人协作的场景，例如核保过程中费率因子异步返回、报价有效期倒计时提醒、代理人端多人同时查看同一报价单的状态同步。
方法流程：报价链路中的协议分层策略
在实际保险系统中，很少只用一种协议。更合理的做法是按链路分层：
- 外部渠道接入层：面向官网、App、第三方平台，优先使用 RESTful API。原因是公网环境复杂，REST 的 HTTP 语义、状态码、缓存机制和调试工具最成熟，接入方学习成本最低。
- 渠道差异化查询层：当同一报价接口需要服务多个字段需求差异大的渠道时，可在 REST 之上引入 GraphQL 网关，让渠道按需声明字段，减少无效数据传输。
- 内部定价引擎层：报价服务与定价引擎、核保引擎、费率服务之间，使用 gRPC。Protobuf 契约能保证字段类型和版本一致性，HTTP/2 多路复用能降低高频报价的延迟。
- 实时状态同步层：报价单有效期提醒、核保异步结果、多人协作报价状态，使用 WebSocket 推送，避免轮询带来的无效请求。
一个典型的车险实时报价链路可以这样组合：App 通过 REST 提交报价请求 → API 网关将请求转为 GraphQL 查询 → 报价服务通过 gRPC 调用定价引擎 → 定价引擎返回费率因子 → 报价服务通过 WebSocket 向 App 推送“报价已生成”状态。四种协议各司其职，而不是互相替代。
案例/场景：不同报价需求的协议匹配
| 报价场景 | 推荐协议 | 关键原因 | 注意事项 |
|---|---|---|---|
| 车险标准报价（单次请求） | RESTful API | 结构简单、渠道通用、易缓存 | 避免在 URL 中暴露敏感参数 |
| 多渠道路由、字段差异大 | GraphQL | 按需取数，减少多次请求 | 需限制查询深度，防止恶意嵌套 |
| 定价引擎内部高频调用 | gRPC | 二进制序列化、低延迟、强类型 | 需维护 Protobuf 版本兼容 |
| 报价状态实时推送 | WebSocket | 服务端主动推送，避免轮询 | 需处理断线重连和消息幂等 |
| 批量报价试算 | gRPC 流式 或 REST 批量 | 流式降低单次连接开销 | 注意超时和背压控制 |
误区/复盘：选型中最容易犯的错误
误区一：所有场景都用 REST。 当报价服务需要每秒处理数千次内部调用时，JSON 序列化和 HTTP/1.1 连接开销会成为瓶颈。此时应把内部链路换成 gRPC，而不是继续优化 REST 参数。
误区二：GraphQL 一定比 REST 好。 GraphQL 的灵活性带来了解析复杂度和缓存难度。如果渠道字段需求稳定，REST 的简单性反而更可靠。GraphQL 更适合字段需求频繁变化的场景。
误区三：WebSocket 可以替代报价请求。 WebSocket 适合推送状态，不适合作为报价主请求通道。报价请求需要明确的请求—响应语义、超时控制和重试策略，这些用 REST 或 gRPC 更清晰。
误区四：忽略协议与网关的兼容性。 部分 API 网关对 gRPC 和 WebSocket 的支持有限，选型时必须确认网关、负载均衡、日志和监控链路是否完整支持，否则会在生产环境出现难以排查的问题。
复盘建议：在报价系统设计初期，先画出完整的报价链路图，标注每一段链路的调用方、被调方、频率、延迟要求和字段变化频率，再根据这些参数选择协议。协议选型不是“哪个先进选哪个”，而是“哪个匹配当前链路的约束”。
# 示例：报价服务中 gRPC 接口的 Protobuf 契约片段
service QuoteService {
rpc GetQuote (QuoteRequest) returns (QuoteResponse);
rpc StreamQuotes (stream QuoteRequest) returns (stream QuoteResponse);
}
message QuoteRequest {
string product_code = 1;
string channel_id = 2;
map<string, string> parameters = 3;
}
message QuoteResponse {
string quote_id = 1;
double premium = 2;
repeated Factor factors = 3;
string status = 4;
}掌握这四种协议的核心差异后，你在设计保险报价 API 时就能做出更有依据的判断：外部接入优先 REST，字段多变考虑 GraphQL，内部高频调用使用 gRPC，实时状态同步交给 WebSocket。协议是工具，报价链路的稳定性、延迟和可维护性才是最终目标。