如何设计REST资源实现跨资源对象查询？REST API功能扩展咨询
2026-7-27
REST API 城市筛选功能的资源与请求方法设计
核心设计原则
因为是获取符合条件的城市资源，统一使用GET请求方法，通过查询参数传递筛选条件——这既符合REST规范，又能灵活支持多种筛选维度（名称、人口、面积等），同时和现有API风格保持一致。
场景1：跨所有国家筛选城市
如果需要从全球所有国家中筛选满足条件的城市，新增顶层城市集合资源：
- 资源路径：
/cities - 请求方法：
GET - 筛选参数示例：
- 按城市名称模糊匹配：
GET /cities?name=Paris - 按人口范围筛选：
GET /cities?minPopulation=1000000&maxPopulation=5000000 - 按面积下限筛选：
GET /cities?minArea=100 - 多条件组合：
GET /cities?name=Lon&minPopulation=8000000
- 按城市名称模糊匹配：
场景2：指定国家内筛选城市
如果仅需要在某个特定国家内筛选城市，直接基于现有资源扩展，在/countries/{countryName}/cities路径上添加查询参数即可：
- 资源路径：
/countries/{countryName}/cities - 请求方法：
GET - 筛选参数示例：
- 按城市名称匹配：
GET /countries/France/cities?name=Lyon - 按人口下限筛选：
GET /countries/Germany/cities?minPopulation=500000 - 多条件组合：
GET /countries/Japan/cities?name=Tokyo&minArea=200
- 按城市名称匹配：
额外设计细节
- 参数命名保持语义化，比如用
minPopulation而非缩写，提升API可读性 - 名称匹配可在后端支持模糊逻辑（如包含、前缀匹配），无需单独设计新路径
- 复杂筛选逻辑（如多条件逻辑组合）仍通过查询参数传递，后端解析处理即可，无需新增资源路径
- 响应结构和现有
/countries/{countryName}/cities的响应保持一致，保证API风格统一
内容的提问来源于stack exchange，提问作者nik0x1
相关产品推荐
相关产品推荐
