4. 金融Serving API设计原则

在金融场景中，模型服务API不只是“把预测结果返回出去”的通道，它同时承担着合规审计、风险隔离、成本控制与稳定性保障四重职责。一个设计粗糙的接口，在行情剧烈波动、批量对账或风控实时决策时，可能因为一次超时、一次鉴权绕过或一次流量洪峰，直接演变为资金与声誉损失。因此，Serving API的设计必须从协议选型、请求响应规范、鉴权、限流、熔断与降级六个维度系统化落地。

一、核心原理：RESTful与gRPC的职责边界

RESTful与gRPC并非互斥，而是面向不同调用方的两种契约。RESTful基于HTTP/1.1与JSON，语义直观、调试成本低，适合面向外部合作方、运营后台、低频查询与人工排查的场景；gRPC基于HTTP/2与Protobuf，具备强类型、双向流、低序列化开销和高并发多路复用能力，适合内部微服务间的高频调用、实时风控打分、批量特征回传等场景。

在金融Serving中，常见做法是“外REST、内gRPC”：网关层暴露RESTful接口给业务方，内部通过gRPC调用推理服务，既保证外部易用性，又保证内部性能。接口设计需遵循统一资源命名、幂等性约束和版本管理，例如/v1/risk/score、/v1/batch/predict，版本号必须出现在路径中，避免破坏性变更影响存量调用方。

二、请求响应规范与鉴权设计

金融API的请求响应必须做到“可预期、可追溯、可校验”。统一响应体建议包含code、message、request_id、data四个字段，其中request_id贯穿网关、推理服务与日志系统，用于全链路追踪。错误码需分层：4xx表示调用方问题（参数错误、鉴权失败、限流拒绝），5xx表示服务端问题（模型超时、依赖不可用）。

鉴权方面，外部接口推荐OAuth2.0客户端凭证模式或+签名，内部gRPC调用推荐mTLS双向证书。所有敏感字段（如身份证号、银行卡号）在日志中必须脱敏，且响应体不得回显完整敏感信息。以下是一个典型的RESTful响应规范示例：

{
  "code": 0,
  "message": "success",
  "request_id": "req_20240612_8f3a9c",
  "data": {
    "score": 0.87,
    "risk_level": "medium",
    "model_version": "risk_v3.2"
  }
}

三、限流、熔断与降级策略

限流解决“入口过载”，熔断解决“依赖故障扩散”，降级解决“核心功能保底”。三者需协同配置，而非孤立存在。

• 限流：按调用方、接口、模型版本三个维度设置配额。常用算法包括令牌桶（允许突发）、滑动窗口（精确统计）。金融场景建议对批量推理接口设置更严格的并发上限。
• 熔断：当推理服务错误率超过阈值（如50%）或P99延迟超过800ms时，自动打开熔断器，快速失败，避免线程池耗尽。半开状态需谨慎探测，防止雪崩。
• 降级：熔断触发后返回兜底结果。例如风控打分降级为“规则引擎结果”，批量推理降级为“异步队列+延迟返回”，并明确告知调用方当前为降级态。

四、案例与常见误区复盘

某消费金融公司在促销活动期间，实时风控接口因未设置调用方维度限流，被一个合作方以每秒3000次请求打满，导致其他合作方全部超时。事后复盘发现：网关仅做了全局QPS限制，未按client_id隔离配额；同时熔断阈值设置过高，未能及时切断异常流量。修正方案是引入“调用方配额+接口优先级+熔断半开探测”三层防护，并将降级策略从“直接报错”改为“返回规则引擎兜底分”。

另一个高频误区是忽略gRPC的截止时间（deadline）传递。若网关未设置deadline，内部调用可能无限等待，拖垮线程池。建议所有gRPC调用强制设置deadline，并在超时后触发降级逻辑。同时，RESTful接口的响应体不宜过大，批量推理结果建议分页或异步回调，避免单次响应超过1MB导致网关内存压力。

最后，所有策略都必须可观测：限流拒绝数、熔断打开次数、降级触发率、P99延迟、错误码分布，这些指标应接入统一监控大盘，并设置分级告警。只有把设计原则转化为可度量、可演练、可回滚的工程实践，金融Serving API才能真正支撑起高并发、低延迟、强合规的业务要求。