RESTFUL URL命名原则

时间:2024-11-16 08:17:30

 

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

 

1.  RESTful优先原则

 

1.1. URL命名原则

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

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

1.2. URL分级

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

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

 

1.3. CRUD请求定义规范(RESTful)

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

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

 

 

/orgz/members

GET

获取成员列表

/orgz/members/120

GET

获取单个成员

/orgz/members

POST

创建成员

/orgz/members/120

PUT

修改成员

/orgz/members

PUT

批量修改

/orgz/members/120

PATCH

修改成员的部分属性

/orgz/members/120

DELETE

删除成员

 

1.4. 复杂查询请求定义规范(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

分页

 

1.5. 特定请求

u  资源的特定请求

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

/module/tickets/recently_closed

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

 

u  非特定资源类

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

1.6. 页面View请求URL规范

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