RESTful 是一种系统开发设计风格、原则。可视情况调整，以下参考来源 RFC5789

Noun

• 一般资源 通用于一律使用复数名词 例如：/books 或 /books/123。但有部分人认为应该使用单数名词，因为： /book/123 看似比 /books/123 合理。但想想文件系统的目录命名（例如 /Users 或 /Documents)，其实用复数也没问题。复数可以保持 API endpoint 的一致性，所以一般资源建议用复数。
• 唯一资源：对 client 而言只有一份的资源 通用于单数名词 例如：user 是指目前验证的使用者，使用者永远只能同时登入一个使用者

Http Method

• Safe：该操作不会改变伺服器端的资源状态（而且结果可以被 cache），属于 Safe 的操作必定属于 Idempotent
• Idempotent (幂等性)：该操作不管做 1 遍或做 n 遍，都会得到同样的资源状态结果（但不一定得到同样的返回值，例如第 2 次 DELETE 请求可能回传 404），因此 client 端可以放心 retry

GET

Safe：每次执行操作时，GET 只有读取 Resource，不会改变到任何的 Resource （资源，资料）
Idempotent：每次执行操作时，GET 只有读取 Resource，不会改变到任何的 Resource （资源，资料），所以任何资源的任何状态都是一样的

POST

每次执行操作时，POST 都会建立一个 Resource （资源，资料）

• Create：建立一个可以完全独立存在的实体

  范例：建立使用者

  执行第一次时：建立一个 name = “李四” 的 user，但其 id = 1，执行第二次时：建立一个 name = “李四” 的 user，但其 id = 2，发送同样的请求，可每次都是不同的 Resource

  建立使用者前不需要建立任何的东西，就可以建立使用者了，使用者是可以完全独立的存在

  1 2 3 4 5 6

  POST /users HTTP/1.1 Host: 127.0.0.1 { "name": "李四" }

• Add：增加一个必须依赖于某个实体的实体

  资料结构：一对多的关系

  范例：Add a public key on behalf of a user 增加一个代表使用者的公钥 (Gitea API)

  增加这个公钥之前，使用者必须存在，公钥必须归属于某个使用者之下，公钥跟姓名一样，使用相同电脑的公钥就会相同，但不表示是同一个使用者，故公钥也会有自己的 ID 我每次增加公钥时，都将生成不同的公钥 ID

  1 2 3 4 5 6 7 8

  POST /api/v1/admin/users/{username}/keys HTTP/1.1 Host: gitea.com { "key": "string", "read_only": true, "title": "string" }

PUT

Idempotent：每次执行操作时，PUT 都会取代 Resource，不管操作几次，使用者获取得 Resource 结果都是一样的

Replace：不论资源如何，最终的资源状态都是一样的，Resource 已存在时，或许不理会、或许先删除后建立（取代）Resource 不存在时，直接建立

Add：添加唯一关系，建立这个唯一关系前，两个关连实体都必须存在。在没有建立关系前，两个关连实体都可以互相独立存在 资料结构：多对多，且两个关连实体的 PK，同时也是关系实体的 PK、FK

• 范例：增加使用者与角色的关系

  增加使用者跟角色的关系前，使用者跟角色都必须存在；增加使用者跟角色的关系前，使用者跟角色可以独立存在， 使用者 12262 跟 角色 2 的关系最多只能有一条关系（ 使用者 12262 有 角色 2)，最少没有关系（使用者 12262 没有 角色 2 ) ，执行第二次操作时，使用者 12262 跟 角色 2 的从属关系仍然存在，也不会跑出第二条 使用者 12262 跟 角色 2 的从属关系

  1 2 3 4 5 6

  PUT user/{account}/roles HTTP/1.1 Host: 127.0.0.1 { "role_id": "2" }

• 范例：Follow a user 关注一个使用者 (Gitea API)

  增加关注关系时，关注者与被关注者（都是使用者） 都必须存在；关注者 12262 跟被关注者 12231 的关系最多只能有一条关系（12262 关注 12231），最少没有关系（12262 不关注 12231），执行第二次操作时，关注者 12262 跟被关注者 12231 的关注关系仍然存在，也不会跑出第二条关注者 12262 跟被关注者 12231 的关注关系

  1 2	PUT /api/v1/user/following/{username} HTTP/1.1 Host: gitea.com

PATCH

Edit：编辑可独立存在、且已经存在的实体，也就是产生新版本的实体，可能会影响其他 Resource

• 范例：编辑使用者

  编辑使用者，使用者已经存在，且我们可能有纪录编辑时间、编辑人、编辑 IP，所以每次的编辑都会造成不一样的结果 第一次编辑使用者，更新时间变为 08:00，编辑人 12262，IP 172.18.0.66 第二次编辑使用者，更新时间变为 09:00，编辑人 12263，IP 172.18.0.67

  1 2 3 4 5 6 7 8

  PATCH /users/{account} HTTP/1.1 Host: 127.0.0.1 { "username": "李四", "age": "18", "gender": "male" }

DELETE

Idempotent：每次执行操作时，DELETE 都会删除相同的东西

• 范例：删除使用者

  第一次删除使用者 12262，删除使用者 12262, 第二次删除使用者 12262，还是删除使用者 12262，只不过使用者 12262 不存在了

  1 2	DELETE /users/{account} HTTP/1.1 Host: 127.0.0.1

HTTP Status Code

HTTP 状态码（HTTP Status Code）是用以表示网页服务器 HTTP 响应状态的 3 位数字代码。所有状态码的第一个数字代表了响应的五种状态之一。除非另有说明，状态码是 HTTP/1.1 标准（RFC 7231）的一部分。

而关于 RESTful API 的请求状态，通常有以下两种设计方案：

• 方案一：使用 HTTP 状态码来表示请求状态，200 时返回的内容就是数据
• 方案二：所有接口都返回 200 ，在响应内容里约定错误码或错误信息

在实际应用中，应据具体情景及需要进行选择与调整。

常用 HTTP 状态码

以上内容参考自https://zh.wikipedia.org/zh-cn/HTTP状态码， 需要查看完整 HTTP 状态码请点击 https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes

• 绝不写死代码，硬编码
• 不留不要用的、垃圾代码

Git

• Master 的 BUG 必须最少且趋近于零，为最稳定的版本
• 每次 Commit 信息应该准确填写。不可模棱两可，eg: 修复 BUG、增加功能
• 禁止 Commit IDE 的 project data，e.g: .vscode
• 禁止上传垃圾代码

更多规则详见文档 Commit 规范

分支（Branch）

• 命名规则：应以此分支主要目的命名（修复什么 BUG，新增特定功能）
• 合并后的分支应该删除

commit

• 遵循一个功能一个 commit 的原则

Restful

• 资源名词站在 API 的角度思考

  • 复数名词：可以复数笔数据，回传结果为 Array

    举例：GET/users 取得多笔使用者资料

    • 刪除，放在复数名词內，让 Router 保持一致性
    • 增加，放在复数名詞內，让 Router 保持一致性

  • 单数名词：仅取得单笔数据，必须指定 PK，两两一组，回传结果为 Object 举例：GET/user/{accont} 取得单笔使用者资料，必须指定 PK

• URL 中一律不带 id 参数

1
2

正确范例： calendar_manager/calendar/29
错误范例： calendar_manager/calendar/29?id=29

更多规则详见文档 RESTful

命名

• 命名应根据内容做有意义的命名，让后续维护人员可以顾名思义！
• 即使不会发生错误，代码英文大小写也需明确区分。

语意

字母与分隔

通用

• 代码编写
• 每个函数应该使用块注释，注释应包含函数功能说明、参数说明。规则见：JSDoc、JavaDoc
• 不必要的代码不要写，也应禁止放到注释里面！
• if-else 的 {} 严禁省略
• 代码规范、代码排版等可通过 eslint 等工具做统一处理

正确写法

1
2
3
4
5
6

public function test () {
  // do something
  if (a === b) {
    // do something
  }
}

错误写法

1
2
3
4
5
6
7
8

public function test ()
{
  // do something
  if (a === b)
  {
    // do something
  }
}

• 代码排版
  • 任何代码应该以 2 个 space 为一个缩进做好排版、不可使用 tab
• 函数 (Function, Methd)
  • 函数声明时需在函数上方加上函数注释，注释应包含函数说明、参数内容（参数类型、参数英文名称、参数说明）、返回值内容（返回值类型、返回值说明）
• 类 (Class)
  • 一个类（Class）的声明只能存在一个文件
  • 类（Class）的声明文件，文件名必须为类名
• 其他
  • 连接本地任何其他资源（图片、文件、网站）皆使用相对路径，禁止使用绝对路径，非本地资源除外

HTML

代码编写

• 禁止在 HTML 使用 <style>、<script>，一律使用外部档案引用方式引用 CSS、JavaScript 文件
• HTML 标签需成双成对，有头有尾
• 块级标签：<tag></tag>
• 单标签：<tag />
• 禁止使用已被 HTML 舍弃的旧标签、属性，如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<!-- html tag -->
<center>
<font>
<basefont>
<s>
<strike>
<u>
<listing>
<plaintext>
<xmp>
<!-- html attribute -->
align
bgcolor
color

CSS

CSS 的定义应该独立一个 CSS 文件，禁止使用 <style> 或 style 属性直接在 HTML 中定义样式。

JavaScript

禁止使用 HTML 字串，一律使用 Dom 产生 HTML, e.g: document.createDocumentFragment()

注释

JavaScript 注释应该遵循 JSDoc 的标准撰写

全局变量 (Global)

1

/* global ZT */

常量 (Constant)

1
2
3
4

/**
 * 常量說明
 * @type {常量类型}
 */

Example

1
2
3
4
5

/**
 * 请求地址
 * @type {String}
 */
const REQUEST_URL = 'http://localhost:8080';

函數、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param {参数类型} 参数名称参数说明
 * @param {参数类型} [选择性参数名称] 参数说明
 * @param {参数类型} [选择性参数名称=参数预设值] 参数说明
 * @returns {返回值类型} 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/**
 * 取得使用者
 * @param {Int} userId 使用者 ID
 * @param {Object} [options] 其他选项
 * @param {String} [options.query='a'] 查询关键词 默认为 'a'
 * @returns {Object} 使用者资料
 */
function getUser(userId, options) {
  // do something
  return user;
}

Vue

• 待补充

Java

Java 注释应该遵循 JavaDoc 的标准撰写

• 待补充

PHP

前端参数取得

参数取得需通过 filter_input 函数取得，不得使用 _GET 、_POST

输出到前台

参数命名必须为：全部小写，不同单字以「_」分隔

注解

PHP 注解应该遵循 PHPDoc 的标准撰写

成员变量 (Member)

成员变量只的是 Class 内的成员变数，我们都会要求替成员变量增加注解说明。通常 Function 的变量除非太特别否则都不需要特别注解说明。

1
2
3
4

/**
 * 成员变量說明
 * @type {类型}
 */

Example

1
2
3
4
5

/**
 * 使用者 ID
 * @type {String}
 */
$userId = 'Hello';

函数、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param 参数型态 参数名称 参数说明
 * @option 参数选项类型 参数选项名称 参数选项说明
 * @uses 全局变量 全域变数说明
 * @returns 返回值类型 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

/**
 * 取得使用者
 * @param int userId 使用者 ID
 * @param object options 其他选项
 * @option string options['query'] 查询关键字
 * @uses $_POST['role_id'] 从前端以 POST 取得角色 ID
 * @returns object 使用者资料
 */
function getUser ($userId, $options) {
  // do something
  return $user;
};

Python

• 待补充

Database

• 禁止使用 Table Join。
• 禁止使用 Oracle Trigger。
• 禁止将查询数据库的 SQL 放在循环中查询

SQL 撰写

• 属于 SQL 语法使用大写（SELECT，WHERE，INSERT etc..）
• 属于使用者自己定义的使用小写（表名 table name，字段名 column name etc..）
• 表名、字段名前后需加上 `

Example

1

INSERT INTO `user` VALUES('a', 'b');

统一用词

系统中常用词，例如弹出框按钮、搜索框等，仅为举例，不限与此。