实践笔记 - 微服务架构下RESTful风格api之我为何抛弃了路由参数

在如今关于 RESTful API 的实践中，许多设计示例经常遵循类似以下的动态路径方案：

方案一：动态路径

方法	路径	描述
GET	/zoos	列出所有的动物园
POST	/zoos	新增一个新的动物园
GET	/zoos/{zoo}	获取指定动物园详情
PUT	/zoos/{zoo}	更新指定动物园
DELETE	/zoos/{zoo}	删除指定动物园
GET	/zoos/{zoo}/animals	检索指定动物园下的动物列表
GET	/animals	列出所有动物

这种设计已经成为许多 RESTful 服务器的主流。然而，仔细研究 RESTful 的核心思想会发现，它并没有强制要求这样的设计，仅仅是建议将服务资源化，并结合 HTTP 方法（而不是仅仅使用 POST）来实现 API 的统一化。比如对于动物园的 API，如果按照以前的设计可能会有 getZooList、updateZoo、deleteZoo 等函数，而资源化之后，主路径只有一个 /zoos，利用不同的 HTTP 方法实现 CRUD 操作。

那么这么做的目的是什么呢？

主要目的是利用 HTTP 的语义来简化和统一 API 的设计。然而，动态路径参数的使用却在无形中增加了路由的复杂度，并没有充分利用单个端点的功能。

如果去掉路由参数，上述 API 可以转化为：

方案二：固定路径

方法	路径	描述
GET	/zoos	获取动物园索引（批量查询）
GET	/zoo?zoo=123&zoo=111	查询指定动物园的信息
POST	/zoo	新增一个动物园
PUT	/zoo	更新一个动物园（信息在请求体中）
DELETE	/zoo	删除某个动物园
GET	/zoo/animals?zoo=123	查询某个动物园的动物列表（批量）
GET	/animals	列出所有动物

这种改动的优点是什么？

安全性提高：动态路由参数需要使用正则匹配路径，容易受到正则匹配攻击——利用特殊参数让正则陷入死循环或耗费大量资源。而固定路径只需简单的路径到处理函数的映射，可以有效避免这类问题。
路由匹配加速：不使用路由参数时路由匹配速度会提升 50%。这种改动降低了路由匹配的复杂度，使请求的解析速度更快，在高并发情况下能够显著提高系统的性能和用户体验。
API 包装和复用：可以更充分地利用固定路径的不同 HTTP 方法。前端不需要拼接复杂的路径，查询参数可以统一封装成 API 工具套件，简化增删改查的调用逻辑。
ID 安全性：路径中的 ID 信息直接暴露存在安全隐患，尤其是用户 ID 等敏感信息。如果将这些信息全部放在请求体中，并通过 HTTPS 传输，至少不会直接暴露在 URL 中。
与 RPC 的对接更方便：这种设计模式可以更方便地与 RPC（如 WebSocket）等端点对接。固定路径使得 API 的调用方式更加稳定，与长连接的接口集成也更加简便。
减少错误可能性：去掉路径参数减少了一个出错的维度，降低了 API 设计的复杂性，减少了开发人员在路径匹配和参数处理方面的工作量。
统一的日志与监控：在固定路径下，所有相同类型的请求路径一致，更便于日志的查询与监控规则的统一配置。统一的路径格式可以更方便地对同类型请求进行聚合统计和异常检测。
简化权限控制：由于路径固定，权限控制逻辑可以更加简单和集中，减少了基于不同路径的复杂权限校验。统一的路径形式使得权限策略更加清晰和可维护，尤其在涉及到多个服务之间的协作时，权限控制可以统一而不混乱。
减少文档复杂度：固定路径的设计可以减少 API 文档的复杂度。每个路径的用途更加明确，开发人员可以更快地理解 API 的使用方式，减少了对 API 文档的误解和困惑，从而提高开发效率。

这种改动的缺点是什么？

URL 变长：固定路径可能会增加 URL 的长度，但如果因此超过了限制，可能需要重新审视设计，明确查询参数的含义。例如，将令牌等敏感信息放在查询参数中显然是错误的做法。长路径可能会对某些设备或浏览器产生影响，但可以通过合理设计参数结构来缓解这个问题。
表达灵活性降低：动态路径有助于直接体现资源之间的层次关系，而固定路径有时会使 URL 看起来不够直观，不便于人类阅读。尤其在涉及到复杂资源关系时，动态路径可以更直观地展示资源的从属和层级关系，而固定路径可能显得过于扁平。
对部分开发者习惯的改变：许多开发者习惯了动态路径的 RESTful 风格，固定路径可能需要开发团队对现有思维方式进行调整。一些工具和框架也对动态路径有较好支持，这种改变可能需要重新配置和调整工具链。

具体例子对比

动态路径方案：
- 获取某个动物园下的动物：GET /zoos/123/animals
- 优点：路径层次清晰，表达资源关系。开发人员可以很容易理解资源之间的关系，尤其在浏览器中查看时更加直观。
固定路径方案：
- 获取某个动物园下的动物：GET /zoo/animals?zoo=123
- 优点：统一路径结构，减少正则匹配的风险。通过统一的路径模式，降低了后端对请求的复杂处理需求，同时简化了前后端的协作。

关于缓存的担忧

浏览器端缓存通常是基于完整路径匹配，因此对这种改动几乎没有影响。对于其他资源的缓存，可以根据需要进行相应设置。例如，可以根据请求的参数配置缓存策略，避免缓存冲突。对于固定路径的请求，缓存策略也可以更加稳定和一致，因为路径形式不会频繁变化，这使得缓存管理变得更加可预测和可靠。

总结

抛弃动态路由参数，改为固定路径的设计，可以简化微服务 API 的实现，提高安全性和可维护性，并更好地与其他系统进行对接。在微服务架构下，API 的清晰简洁显得尤为重要，而固定路径的设计理念则提供了一种更加一致和直观的方式来构建 RESTful API。这种设计不仅提高了系统的安全性，还使得 API 的管理和维护变得更加高效。同时，固定路径的结构使得开发者能够更加专注于业务逻辑的实现，而不是在复杂的路径匹配和解析上浪费精力。因此，在考虑到微服务架构的扩展性和可维护性时，固定路径的设计显得尤为合适。通过这种方式，可以实现更加稳定、可扩展且易于维护的 API 体系，为未来的扩展和集成打下坚实的基础。