URL规范

目录

背景和价值

1 路径规范
restful api的路径对后端开发不友好。观看路径，不看资源操作类型，无法区分是读，还是写操作。在我们团队使用局部restful的形式。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

1.1 BFF路径

子产品/领域/功能/, 子产品如 商城，运营端，IT管理后台。
https://api.example.com/bff/v1/mall/order/placeOrder (动宾结构)
https://api.example.com/bff/v1/mall/order/queryOrderById(动宾结构)

1.2 服务提供者路径

路径规范 /领域/功能/
https://api.example.com/v1/api/order/placeOrder (动宾结构)
https://api.example.com/v1/api/order/queryOrderById(动宾结构)

2 api 版本 升级规范

api不兼容的升级，需要升级版本
原接口 http://localhost:8080/v1/user/get_user
由于接口协议变化大，无法兼容老接口，需要新增接口
新接口http://localhost:8080/v2/user/get_user

3 其他规范

get请求不允许使用http请求体。
涉及新增、修改的接口不能用get请求
参考资料
https://www.ruanyifeng.com/blog/2014/05/restful_api.html

版本放哪里？

Google/Microsoft/Amazon 规范​
顶级科技公司均采用 api/{version}/{resource} 格式：
Google: https://service.endpoints.example.com/v1/instances
Microsoft Graph: https://graph.microsoft.com/v1.0/me/messages
Amazon AWS: /ec2/v1/instances
​核心逻辑​：api 作为服务入口标识，版本号紧随其后，体现“先服务后版本”的分层逻辑

如果分子产品
api/领域/{version}/{resource}

什么情况下会发生全局版本升级

在API版本管理中，全局升级版本（即主版本号变更）通常发生在以下关键场景中，需通过大规模调整服务端逻辑或客户端适配实现全面升级：

一、重大架构或协议变更

当API底层架构（如从REST转向GraphQL）或通信协议（如HTTP/1.1升级到HTTP/3）发生不兼容变更时，需全局升级。例如：

  • 电商平台重构订单系统，将原本基于数据库ID的查询改为分布式全局ID，导致所有订单接口的输入输出格式变更。
  • 金融支付系统从RSA加密迁移到国密SM2算法，所有涉及加密签名的接口需统一升级。

二、核心业务逻辑重构

若API的核心功能行为发生颠覆性调整，需强制全局升级版本：

  • 社交媒体平台将用户关注关系从单向改为双向（如微信好友模式），所有用户关系接口需重新定义字段和交互规则。
  • 物流系统将配送状态从“三段式”（已揽件、运输中、已签收）扩展为“五段式”（新增分拣中、派送中），涉及所有订单状态查询接口。

三、安全漏洞修复与合规要求

当发现高危安全漏洞或需满足强制性法律法规时，需立即全局升级：

  • 用户隐私数据接口因GDPR合规要求，需将手机号字段从明文返回改为掩码（如138****5678），所有相关接口必须升级。
  • OAuth 2.0授权接口存在令牌泄露风险，需废弃旧版本并全局切换到带有令牌绑定机制的v2版本。

四、技术栈迁移

因技术栈升级（如编程语言、框架或数据库更换）导致的不可逆兼容性破坏：

  • 后端服务从Java 8升级到Java 17，因语法特性变更导致部分API序列化协议不兼容。
  • 数据库从MySQL迁移到TiDB，因分布式事务特性差异需调整所有事务型接口。

五、长期维护成本过高

当旧版本API的维护成本远超收益时，需通过全局升级实现统一治理：

  • 某电商平台同时维护5个历史版本API，因测试和文档更新成本过高，决定强制淘汰v1-v3版本，仅支持v4及以上版本。
  • 地图服务API因旧版地图数据格式存储效率低下，需全面升级到矢量压缩格式。

全局升级注意事项

  1. 文档同步更新
    需在升级前发布新版API文档，明确标注废弃字段、行为变更点及迁移指南。
  2. 过渡期设置
    建议设置3-6个月过渡期，通过HTTP 410 Gone状态码引导旧版本调用方迁移。
  3. 自动化工具支持
    提供SDK升级脚本、Postman集合转换工具等，降低开发者适配成本。

全局升级是系统性工程，需结合灰度发布、AB测试等手段降低风险。建议优先通过兼容层或特性开关（Feature Flag）实现渐进式升级，仅在必要时采用全局强制升级策略。

参考资料

posted @ 2025-05-27 15:39  向着朝阳  阅读(31)  评论(0)    收藏  举报