📚 课程目录第2章 API发布基础

2. API 发布基础：生命周期、版本控制与文档规范

在贷后风控场景中，API 从设计到下线并非一次性动作，而是一个持续迭代、受控发布的过程。本章聚焦 API 发布的三项核心基础：生命周期管理确保每个阶段可追溯、可回滚；版本控制策略保障多版本并行时的兼容性与平滑迁移；文档规范（OpenAPI/Swagger）实现人与机器对接口契约的一致理解。这三者共同构成贷后风控 API 治理的基石。

2.1 API 生命周期管理

API 生命周期通常划分为 6 个阶段，每个阶段都有明确的准入/准出标准。贷后风控 API 因涉及敏感数据和资金安全，在“测试”与“发布”阶段需额外增加安全审计与压力测试关卡。

阶段	关键活动	贷后风控特殊要求
设计	定义资源、请求/响应结构、错误码	必须包含脱敏字段标记、敏感数据分级
开发	编码实现、单元测试、接口 Mock	代码需通过静态安全扫描（SAST）
测试	功能测试、集成测试、性能测试	必须通过 200% 峰值流量压测、数据隔离验证
发布	灰度发布、全量上线、监控接入	灰度比例 ≤10%，观察期 ≥24 小时
运营	监控告警、日志审计、限流熔断	实时监控响应时间、错误率、数据一致性
下线	流量摘除、数据清理、文档归档	下线前需确认无存量调用，保留审计日志 180 天

实践建议：在 API 网关（如 Kong、APISIX）中为每个阶段设置标签（tag），例如 status:design、status:testing，便于自动化流水线识别当前阶段并执行对应的路由策略。

2.2 API 版本控制策略

贷后风控系统通常需要同时服务多个合作方（银行、消费金融公司、催收机构），不同合作方对接的 API 版本可能不同。版本控制策略的核心目标是：向前兼容与平滑迁移。

2.2.1 三种主流版本策略对比

策略	实现方式	优点	缺点	贷后风控适用场景
URI 路径	`/v1/overdue/query`	直观、路由简单	URL 膨胀、语义耦合	对外暴露的 RESTful 接口
请求头	`Accept: application/vnd.risk.v2+json`	URL 干净、版本与资源解耦	调试不便、网关需解析 Header	内部微服务间调用
查询参数	`/overdue/query?version=2`	实现灵活、兼容旧客户端	参数污染、缓存命中率低	临时过渡期、灰度验证

  推荐做法：贷后风控 API 网关层统一采用 URI 路径 + 请求头双轨制。对外暴露使用路径版本（如 /v2/overdue/query），内部路由转发时附加版本 Header，便于网关做精细化流量调度与版本灰度。

2.2.2 版本生命周期与废弃策略

每个 API 版本都应设定明确的废弃时间线，避免无限期维护旧版本。以下是一个典型的贷后风控版本废弃时间表：

v1.0：当前稳定版本，全量流量
v1.1：新增字段（向后兼容），与 v1.0 共享同一路由
v2.0：破坏性变更（如请求结构重构），新合作方强制使用
废弃策略：v1.0 发布后第 6 个月标记为“废弃”，第 9 个月停止服务，期间返回 Warning 响应头提醒升级

// 废弃响应头示例
HTTP/1.1 200 OK
Content-Type: application/json
Warning: 299 - "API version v1 will be deprecated on 2025-09-30. Please migrate to v2."
Sunset: Sat, 30 Sep 2025 23:59:59 GMT

2.3 API 文档规范（OpenAPI / Swagger）

OpenAPI 规范（原 Swagger）是描述 RESTful API 的事实标准。在贷后风控场景中，一份高质量的 OpenAPI 文档不仅是开发者的参考手册，更是自动化测试、网关配置、安全审计的单一事实来源。

2.3.1 贷后风控 OpenAPI 文档核心要素

要素	说明	贷后风控示例
info	API 名称、版本、描述、联系人	`title: 贷后风控查询接口`
servers	基础 URL，区分环境	`url: https://api.risk.example.com/v2`
paths	每个端点的请求/响应定义	`/overdue/query` POST
components/schemas	数据模型定义，支持复用	`OverdueRequest`、`OverdueResponse`
security	认证方式（API Key、OAuth2）	`apiKey: X-API-Key`
tags	接口分组，便于文档导航	`name: 逾期查询`

2.3.2 一个完整的贷后风控接口定义片段

openapi: 3.0.3
info:
  title: 贷后风控逾期查询接口
  version: 2.0.0
  description: 用于查询借款人的逾期状态、逾期天数及催收阶段
servers:
  - url: https://api.risk.example.com/v2
paths:
  /overdue/query:
    post:
      summary: 查询逾期信息
      tags: [逾期查询]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OverdueRequest'
      responses:
        '200':
          description: 成功返回逾期数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverdueResponse'
        '400':
          description: 请求参数错误
        '401':
          description: 认证失败
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    OverdueRequest:
      type: object
      required: [loanId, queryDate]
      properties:
        loanId:
          type: string
          description: 贷款唯一编号
        queryDate:
          type: string
          format: date
          description: 查询日期
    OverdueResponse:
      type: object
      properties:
        loanId:
          type: string
        overdueDays:
          type: integer
          description: 逾期天数
        collectionStage:
          type: string
          enum: [M0, M1, M2, M3+]
          description: 催收阶段

安全提醒：贷后风控 OpenAPI 文档中禁止暴露真实数据库字段名、内部 IP、端口或加密密钥。建议在 CI/CD 流水线中自动对文档进行脱敏扫描，确保发布到开发者门户的文档不包含敏感信息。

2.4 本章小结

API 生命周期：6 阶段状态机，贷后风控需在测试与发布阶段增加安全审计与灰度观察。
版本控制：URI 路径 + 请求头双轨制最适合贷后风控场景；废弃策略需提前 6 个月通知合作方。
文档规范：OpenAPI 3.0 是贷后风控 API 的契约基础，必须包含安全认证、数据模型、错误码定义，并纳入 CI/CD 流水线。