OpenAPI3环境下RESTful接口通过双唯一参数查询单实体的设计方案

核心结论 #

直接新增基于业务唯一键的单资源路径即可，完全符合REST规范，且兼容原有遗留接口：
/v1/{customer}/types/codes/{code}

方案说明 #

• 合规性逻辑：REST规范从未要求资源路径中必须携带数据库自增ID，只要路径参数组合能唯一标识一个资源即可。你的场景中customer + code已经是数据库级别的唯一约束，天然可以作为Type资源的合法业务唯一标识符
• 兼容性：该路径和原有/v1/{customer}/types/{id}接口完全独立，不会影响存量业务的调用，适配遗留项目成本极低
• 语义清晰度：路径直接指向单个Type资源，接口直接返回单实体结构体，不需要返回列表，完全避免你提到的查询参数方案的语义歧义问题
• OpenAPI3适配：可以直接在现有接口定义基础上复用Type资源的响应Schema，仅需新增路径和对应参数定义即可，无冗余开发量

备选方案（仅推荐无格式冲突场景使用） #

如果你的Type资源的自增ID和code存在明确的格式差异（比如ID是纯数字、code至少包含1个非数字字符），也可以简化路径为：
/v1/{customer}/types/{code}
你可以在OpenAPI3定义中通过pattern参数明确区分两个路径的参数格式，服务端路由框架可自动匹配对应接口，不会出现路由冲突。

不推荐方案的补充说明 #

你提到的/v1/{customer}/types?code=123查询参数方案并非完全不可用，你也可以自行定义该接口在传入唯一code参数时返回单实体而非列表，但因为路径本身指向的是集合资源，语义上和单实体返回存在歧义，不符合REST最佳实践，因此不优先推荐。

内容的提问来源于stack exchange，提问作者Dan Serb