REST API系列—（2）REST API URI 设计规范文档

最新推荐文章于 2026-06-15 17:32:20 发布

原创

最新推荐文章于 2026-06-15 17:32:20 发布 · 890 阅读

标签

#设计规范 #REST

适用范围：后端服务 / IoT 云平台 / Web 应用 / 移动端 API

1. 概述

REST（Representational State Transfer）是一种基于 HTTP 协议的资源导向型架构风格。

URI（Uniform Resource Identifier，统一资源标识符）是 REST API 的核心，用于唯一标识系统中的资源。

本规范旨在统一 REST API 的 URI 设计规则，提高系统一致性、可维护性与可扩展性。

分类	规则	示例
命名风格	全小写、单词间使用 - 连接	/user-roles, /device-logs
资源命名	使用名词（复数）表示集合	/users, /devices
单个资源	使用唯一标识符 {id}	/users/{userId}, /devices/{deviceId}
资源关系	使用层级结构表达从属关系	/users/{userId}/orders/{orderId}
操作动作	使用子资源表达动作（不用动词）	/devices/{id}/lock
查询参数	用于过滤、分页、排序	/devices?status=active&page=1&size=20
禁止动词	不得在 URI 中使用动作词	❌ /getUser ✅ /users/{id}
文件路径命名	统一前缀 /api/v{version}/...	/api/v1/devices

/users
/devices
/orders

/users/{userId}
/devices/{deviceId}
/orders/{orderId}

/users/{userId}/orders
/users/{userId}/orders/{orderId}
/devices/{deviceId}/logs

POST /devices/{deviceId}/unlock
POST /devices/{deviceId}/lock

HTTP 方法	含义	示例 URI	行为描述
GET<