/tags/%E6%9E%B6%E6%9E%84%E6%BC%94%E8%BF%9B/ Recent content in 架构演进 on Hugo -- gohugo.io en Sun, 26 Apr 2026 12:45:14 +0800 /posts/api-versioning-strategies/ Sun, 26 Apr 2026 12:45:14 +0800 /posts/api-versioning-strategies/ API 版本管理是微服务架构中一个看似简单、实则充满细节的话题。客户端很多，升级节奏也各不相同，一个"破坏性变更"稍有不慎就可能让线上支付或推送流程出问题。本文尝试梳理四种主流策略，并逐一对比 Spring Boot 4 原生支持与历史实现方案，最后总结生产环境中常见的问题。 为什么需要版本管理 REST API 一旦对外发布，就变成了一份"隐式合同"。只要还有一个客户端在运行，你就不能随意更改字段含义、删除字段或修改响应结构。版本管理的本质，是为破坏性变更（Breaking Change）提供一条可控的演进通道，让新旧客户端能在同一套基础设施上共存。 什么算 Breaking Change？ 删除或重命名字段 修改字段类型（如 amount: int → amount: BigDecimal） 修改 HTTP 状态码语义 业务流程从同步改为异步 认证机制变更（如从 API Key 改为 OAuth2） 非破坏性变更（如新增可选字段、新增接口）通常不需要升版本。 四种主流策略 1. URL 路径版本化 版本号嵌入 URL 路径，是目前很常见的方案，Stripe、GitHub、PayPal 等公开 API 也都能看到这种风格。 GET /api/v1/payments GET /api/v2/payments 优点： 直观、易调试、网关路由配置简单（前缀匹配）、Swagger 文档可以生成完全隔离的两套页面。 缺点： 粒度较粗。90% 的接口没有变化，但客户端却需要将所有调用路径从 /v1/ 改为 /v2/。 关于 /api/v1/payments 与 /api/payments/v1 的选择：前者将版本视为整个 API 服务的快照，网关路由更友好；后者将版本视为某个资源的属性，粒度更细但运维复杂度更高。在我接触到的大多数团队里，前者更常见。 2. 查询参数版本化 版本号以 Query Parameter 的形式传递： GET /api/payments?version=1 GET /api/payments? /posts/openapi-31-upgrade/ Fri, 10 Apr 2026 14:00:00 +0800 /posts/openapi-31-upgrade/ 📦 本文基于的完整项目源码：https://github.com/meirongdev/shop 🏷️ 当前文章对应的代码版本：openapi_3_1_upgrade 背景 我们的电商平台自启动以来，一直使用 OpenAPI 3.0.x 作为 API 文档规范。近期在整理 SpringDoc 2.8.9 和 JSON Schema 2020-12 工具链时，我顺手验证了一次 OpenAPI 3.1 升级的可行性，最后决定先在项目里试着切过去。 就这次实践看，升级过程主要是一行配置，没有涉及 Java 代码改动。下面更像是一份升级笔记：记录我为什么做这件事、哪些收益比较直接，以及哪些兼容性边界要先确认。 OpenAPI 3.1 的核心变化 OpenAPI 3.1 于 2021 年底发布（官方发布公告），虽然看起来只是小版本号 +1，但它底层做了一个根本性的改变：全面对齐 JSON Schema Draft 2020-12（JSON Schema 2020-12 规范）。 这不只是"换了一个标准"，更像是把 OpenAPI Schema 往 JSON Schema 工具链上靠近了一步。 变化一：nullable 语义重构 OpenAPI 3.0 的写法： { "type": "string", "nullable": true } 这是一个 OpenAPI 自定义扩展字段。JSON Schema 标准中不存在 nullable，这意味着： 标准 JSON Schema 校验器不认识它 代码生成器需要专门处理 OpenAPI 特有的逻辑 与 JSON Schema 生态工具链不互通 OpenAPI 3.