RESTFUL URL命名原则

时间 2021-01-19 标签接口命名规则 restful

URL命名通常有三种，驼峰命名法(serverAddress)，蛇形命名法(server_address)，脊柱命名法(server-address)。由于URL是大小写敏感的，如果用驼峰命名在输入的时候就要求区分大小写，一个是增加输入难度，另外也容易输错，报404。蛇形命名法用下划线，在输入的时候需要切换shfit，同时下划线容易被文本编辑器的下划线掩盖，支付宝用的是蛇形命名法，stackoverflow.com和github.com用的是脊柱命名法（例如https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user 和(\https://stackoverflow.com/questions/5262224/how-are-reddit-and-hacker-news-ranking-algorithms-used）

1. RESTful优先原则

1、 URL请求采用小写字母，数字，部分特殊符号（非制表符）组成。

2、 URL请求中不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接符“_”连接单词

第一级Pattern为模块,比如组织管理/orgz, 网格化：/grid

第二级Pattern为资源分类或者功能请求，优先采用资源分类

如果为资源分类，则按照RESTful的方式定义第三级Pattern，

RESTful规范中，资源必须采用资源的名词复数定义。

/module/tickets?state=open	GET	过滤
/module/tickets?sort=-priority	GET	排序
/module/tickets?sort=-priority,created_at	GET	排序
/module/tickets?sort=-updated_at	GET	排序
/module/tickets?state=closed&sort=-updated_at	GET	过滤+排序
/module/tickets?q=return&state=open&sort=-priority,created_at	GET	搜索+过滤+排序
/module/tickets/recently_closed	GET	一般数据请求
/module/tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at	GET	指定返回列
/cars?offset=10&limit=5	GET	分页

u 资源的特定请求

采用在资源下面定义特定的请求pattern，见如下示例

/module/tickets/recently_closed

备注：此情况下需要区分/module/tickets/{id}，要避免URL无法区分，通用的配置请求要具备优先适配能力。

u 非特定资源类

请求URL采用如下形式: /module/buy_tickets

页面URL仅定义在第二级，例如/orgz/xxx，xxx为orgz模块的视图名称名称。