以下参考来源：阮一峰的 中文技术文档的写作规范

英语世界里，文档非常受重视，许多公司和组织都有自己的文档规范，清楚地规定写作要求，比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等（维基百科有一份完整的清单）。中文的也有不少，但都不令人满意，要么太简单，要么不太适用。

对于开发者来说，在工作中也需要适当地产出一些技术文档，但是很多人都不知道怎么写文档，都是凭着感觉写。

对于开发的系统、软件而言，系统用词的准确性和统一性也显得十分重要。

参考上面的规范，于是有了下面一份中文技术文档的写作规范。

标题

层级

标题分为四级。

• 一级标题：文章的标题
• 二级标题：文章主要部分的大标题
• 三级标题：二级标题下面一级的小标题
• 四级标题：三级标题下面某一方面的小标题

下面是示例。

1
2
3
4
5
6
7

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

注：最多支持六级，但是同论文写作一样，层级太深，会使得整体显得杂乱无章，当确实需要更深层级时，应另起新篇单独论述。

原则

（1）一级标题下，不能直接出现三级标题。

示例：下面的文章结构，缺少二级标题。

1
2
3

# 一级标题

### 三级标题

（2）标题要避免孤立编号（即同级标题只有一个）。

示例：下面的文章结构，二级标题 A只包含一个三级标题，完全可以省略三级标题 A。

1
2
3
4
5

## 二级标题 A

### 三级标题 A

## 二级标题 B

（3）下级标题不重复上一级标题的名字。

示例：下面的文章结构，二级标题与下属的三级标题同名，建议避免。

1
2
3

## 概述

### 概述

（4）谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。

如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。

示例：下面的结构二要好于结构一。结构一适用的场景，主要是较长篇幅的内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

#### 四级标题 C

结构二

### 三级标题

**（1）A**

**（2）B**

**（3）C**

文本

字间距

（1）全角中文字符与半角英文字符之间，应有一个半角空格。

1
2
3

错误：本文介绍如何快速启动Windows系统。

正确：本文介绍如何快速启动 Windows 系统。

（2）全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。

1
2
3

正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。

半角的百分号，视同阿拉伯数字。

1
2
3

正确：今年我国经济增长率是6.5%。

正确：今年我国经济增长率是 6.5%。

（3）英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。

1
2
3

例1：一部容量为 16 GB 的智能手机

例2：1 h = 60 min = 3,600 s

（4）半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

1
2
3

错误：他的电脑是 MacBook Air 。

正确：他的电脑是 MacBook Air。

句子

（1）避免使用长句。

不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20 ～ 29 个字的句子，可以接受；30 ～ 39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。

1
2
3

错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

逗号分割的长句，总长度不应该超过 100 字或者正文的 3 行。

（2）尽量使用简单句和并列句，避免使用复合句。

1
2
3

并列句：他昨天生病了，没有参加会议。

复合句：那个昨天生病的人没有参加会议。

（3）同样一个意思，尽量使用肯定句表达，不使用否定句表达。

1
2
3

错误：请确认没有接通装置的电源。

正确：请确认装置的电源已关闭。

（4）避免使用双重否定句。

1
2
3

错误：没有删除权限的用户，不能删除此文件。

正确：用户必须拥有删除权限，才能删除此文件。

写作风格

（1）尽量不使用被动语态，改为使用主动语态。

1
2
3

错误：假如此软件尚未被安装，

正确：假如尚未安装这个软件，

（2）不使用非正式的语言风格。

1
2
3

错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！

正确：无法参加本次活动，我深感遗憾。

（3）不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。

1
2
3

错误：这是唯二的快速启动的方法。

正确：这是仅有的两种快速启动的方法。

（4）用对“的”、“地”、“得”。

1
2
3
4
5
6
7
8

她露出了开心的笑容。
（形容词＋的＋名词）

她开心地笑了。
（副词＋地＋动词）

她笑得很开心。
（动词＋得＋副词）

（5）使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。

1
2
3

错误：从管理系统可以监视中继系统和受其直接控制的分配系统。

正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。

（6）名词前不要使用过多的形容词。

1
2
3

错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

英文处理

（1）英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。

1
2
3

英文：...information stored in random access memory (RAMs)...

中文：⋯⋯存储在随机存取存储器（RAM）里的信息⋯⋯

（2）外文缩写可以使用半角圆点(.)表示缩写。

1
2

U.S.A.
Apple, Inc.

（3）表示中文时，英文省略号（...）应改为中文省略号（⋯⋯）。

1
2
3

英文：5 minutes later...

中文：5 分钟过去了⋯⋯

（4）英文书名或电影名改用中文表达时，双引号应改为书名号。

1
2
3

英文：He published an article entitled "The Future of the Aviation".

中文：他发表了一篇名为《航空业的未来》的文章。

（5）第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。

1

IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。

（6）专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。

1
2
3

“American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。

“online transaction processing”（在线事务处理）不是专有名词，不应大写。

段落

原则

• 一个段落只能有一个主题，或一个中心句子。
• 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务。
• 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
• 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
• 段落之间使用一个空行隔开。
• 段落开头不要留出空白字符。

引用

引用第三方内容时，应注明出处。

1

One man’s constant is another man’s variable. — Alan Perlis

如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。

1

本文转载自 WikiQuote

使用外部图片时，必须在图片下方或文末标明来源。

1

本文部分图片来自 Wikipedia

数值

半角数字

阿拉伯数字一律使用半角形式，不得使用全角形式。

1
2
3

错误：这件商品的价格是１０００元。

正确：这件商品的价格是 1000 元。

千分号

数值为千位以上，应添加千分号（半角逗号）。

1

XXX 公司的实收资本为 ￥1,258,000 人民币。

对于 4 位的数值，千分号是选用的，比如1000和1,000都可以接受。对于 4 位以上的数值，应添加千分号。

货币

货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

1
2

$1,000
1,000 美元

英文的货币名称，建议参考国际标准 ISO 4217。

数值范围

表示数值范围时，用波浪线（～）或一字线（—）连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时，两个数字建议都要加上单位或百分号。

1
2
3

132 kg～234 kg

67%～89%

变化程度的表示法

数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

1
2
3
4
5

增加到过去的两倍
（过去为一，现在为二）

增加了两倍
（过去为一，现在为三）

数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。

1
2
3
4
5

降低到百分之八十
（定额是一百，现在是八十）

降低了百分之八十
（原来是一百，现在是二十）

不能用“降低 N 倍”或“减少 N 倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。

标点符号

原则

（1）中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉的一致。

（2）如果整句为英文，则该句使用英文/半角标点。

（3）句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。

（4）点号（句号、逗号、顿号、分号、冒号）不得出现在标题的末尾，而标号（引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号）可以。

句号

（1）中文语句的结尾处应该用全角句号（。）。

（2）句子末尾用括号加注时，句号应在括号之外。

1
2
3

错误：关于文件的输出，请参照第 1.3 节（见第 26 页。）

正确：关于文件的输出，请参照第 1.3 节（见第 26 页）。

逗号

（1）逗号（，）表示句子内部的一般性停顿。

（2）注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。

顿号

（1）句子内部的并列词，应该用全角顿号(、) 分隔，而不用逗号，即使并列词是英语也是如此。

1
2
3

错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

（2）英文句子中，并列词语之间使用半角逗号（,）分隔。

1

例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.

（3）中文句子内部的并列词，最后一个尽量使用（和）来连接，使句子读起来更加连贯，下面两个句子都可以，第二个更优。

1
2
3

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里，以及百度等。

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

分号

（1）分号（；）表示复句内部并列分句之间的停顿。

引号

（1）引用时，应该使用全角双引号（“ ”），注意前后双引号不同。

1

例句：许多人都认为客户服务的核心是“友好”和“专业”。

（2）引号里面还要用引号时，外面一层用双引号，里面一层用单引号（‘ ’），注意前后单引号不同。

1

例句：鲍勃解释道：“我要放音乐，可萨利说，‘不行！’。”

括号

（1）补充说明时，使用全角圆括号（（）），括号前后不加空格。

1

例句：请确认所有的连接（电缆和接插件）均安装牢固。

（2）几种括号的中英文名称。

冒号

（1）全角冒号（：）常用在需要解释的词语后边，引出解释和说明。

1

例句：请确认以下几项内容：时间、地点、活动名称和来宾数量。

（2）表示时间时，应使用半角冒号（:）。

1

例句：早上 8:00

省略号

（1）省略号（⋯⋯）表示语句未完、或者语气的不连续。

（2）省略号占两个汉字空间、包含六个省略点，不要使用。。。或...等非标准形式。

（3）省略号不应与“等”这个词一起使用。

1
2
3
4
5

错误：我们为会餐准备了香蕉、苹果、梨…等各色水果。

正确：我们为会餐准备了各色水果，有香蕉、苹果、梨⋯⋯

正确：我们为会餐准备了香蕉、苹果、梨等各色水果。

感叹号

（1）应该使用平静的语气叙述，尽量避免使用感叹号（！）。

（2）不得多个感叹号连用，比如！！和!!!。

破折号

（1）破折号————一般用于进一步解释。

（2）破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。

1
2
3

例句：直觉————尽管它并不总是可靠的————告诉我，这事可能出了些问题。

例句：直觉 —— 尽管它并不总是可靠的 —— 告诉我，这事可能出了些问题。

连接号

（1）连接号用于连接两个类似的词。

（2）以下场合应该使用直线连接号（-），占一个半角字符的位置。

• 两个名词的复合
• 图表编号

1
2
3

例句：氧化-还原反应

例句：图 1-1

（3）数值范围（例如日期、时间或数字）应该使用波浪连接号（～）或一字号（—），占一个全角字符的位置。

1

例句：2009 年～2011 年

注意，波浪连接号前后两个值都建议加上单位。

（4）波浪连接号也可以用汉字“至”代替。

1

例句：周围温度：-20 °C 至 -10 °C

文档体系

结构

软件手册是一部完整的书，建议采用下面的结构。

• 简介（Introduction）：[必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
• 快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
• 入门篇（Basics）：[必备] [目录] 又称“使用篇”，提供初级的使用教程
  • 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
  • 安装（Installation）：[可选] [文件] 软件的安装方法
  • 设置（Configuration）：[必备] [文件] 软件的设置
• 进阶篇（Advanced)：[可选] [目录] 又称“开发篇”，提供中高级的开发教程
• API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
• FAQ：[可选] [文件] 常见问题解答
• 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
  • Glossary：[可选] [文件] 名词解释
  • Recipes：[可选] [文件] 最佳实践
  • Troubleshooting：[可选] [文件] 故障处理
  • ChangeLog：[可选] [文件] 版本说明
  • Feedback：[可选] [文件] 反馈方式

下面是两个真实范例，可参考。

• Redux 手册
• Atom 手册

文件名

文档的文件名不得含有空格。

文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。

1
2
3

错误：名词解释.md

正确：glossary.md

文件名建议只使用小写字母，不使用大写字母。

1
2
3

错误：TroubleShooting.md

正确：troubleshooting.md

为了醒目，某些说明文件的文件名，可以使用大写字母，比如README、LICENSE。

文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。

1
2
3

不佳：advanced_usage.md

正确：advanced-usage.md

参考链接

• 产品手册中文写作规范, by 华为
• 写作规范和格式规范, by DaoCloud
• 技术写作技巧在日汉翻译中的应用, by 刘方
• 简体中文规范指南, by lengoo
• 文档风格指南, by LeanCloud
• 豌豆荚文案风格指南, by 豌豆荚
• 中文文案排版指北, by sparanoid
• 中文排版需求, by W3C
• 为什么文件名要小写？, by 阮一峰
• Google Developer Documentation Style Guide, by Google
• 出版物上数字用法的规定（国家标准 GBT15835－2011）
• GB 3100-1993 国际单位制及其应用
• markdownlint, VSCode 插件
• pangu.js, 盘古之白系列插件

格式

基本的语法格式如下，更多请参考 Backus–Naur Form Grammar for Valid SemVer Versions

1
2
3
4

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

范例：

规范

以下关键词 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、 RECOMMENDED、MAY、OPTIONAL 依照 RFC 2119 的叙述解读。

版本阶段

• Base: 设计阶段，只有相应的设计没有具体的功能实现
• Alpha: 软件的初级版本，基本功能已经实现，但存在较多的 bug
• Bate: 相对于 Alpha 已经有了很大的进步，消除了严重的 BUG，但还存在一些潜在的 BUG，还需要不断测试
• RC: 该版本已经相当成熟了，基本上不存在导致错误的 Bug，与即将发行的正式版本相差无几
• RELEASE: 最终发布版本，没有太大的问题

最终发布版本（RELEASE）之前的所有版本，都称为先行版本（pre-release）。

FAQ

其他相关

npm SemVer

通常我们发布一个包到 npm 仓库时，我们的做法是先修改 package.json 为某个版本，然后执行 npm publish 命令。手动修改版本号的做法建立在你对 SemVer 规范特别熟悉的基础之上，否则可能会造成版本混乱。npm 和 yarn 两个包管理都提供了 SemVer 规范的版本控制命令：

• npm-version
• yarn version

npm 发包基础命令：

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

# 1. 创建一个新的包
npm init
# 2. 查看是否官方源
npm config get registry
# 3. 登录
npm login
# 4. 发布
npm publish

# 版本变化 major.minor.patch
npm version patch # 升级补丁版本
npm version minor # 升级小版号
npm version major # 升级大版号

# 下架 [-force]
npm unpublish

全局设置版本号前缀

1
2
3
4
5

# https://docs.npmjs.com/cli/v8/using-npm/config#tag-version-prefix
npm config set tag-version-prefix ""
# 全局设置版本更新 commit 提交信息
# https://docs.npmjs.com/cli/v8/using-npm/config#message
npm config set message "Chore(release): %s"

或者设置项目的 .npmrc 或者 .yarnrc

1
2
3
4
5
6
7

# .npmrc
tag-version-prefix=""
message="Chore(release): %s"

# .yarnrc
version-tag-prefix ""
version-git-message "Chore(release): %s"

package.json 版本控制规则使用了一些些符号：

• ^
• ~
• >
• >=
• <
• <=
• =
• -
• ||

这些规则的详情如下：

• ^: 只会执行不更改最左边非零数字的更新。 如果写入的是 ^0.13.0，则当运行 npm update 时，可以更新到 0.13.1、0.13.2 等，但不能更新到 0.14.0 或更高版本。 如果写入的是 ^1.13.0，则当运行 npm update 时，可以更新到 1.13.1、1.14.0 等，但不能更新到 2.0.0 或更高版本。
• ~: 如果写入的是 〜0.13.0，则当运行 npm update 时，会更新到补丁版本：即 0.13.1 可以，但 0.14.0 不可以。
• >: 接受高于指定版本的任何版本。
• >=: 接受等于或高于指定版本的任何版本。
• <=: 接受等于或低于指定版本的任何版本。
• <: 接受低于指定版本的任何版本。
• =: 接受确切的版本。
• -: 接受一定范围的版本。例如：2.1.0 - 2.6.2。
• ||: 组合集合。例如 < 2.1 || > 2.6。

可以合并其中的一些符号，例如 1.0.0 || >=1.1.0 <1.2.0，即使用 1.0.0 或从 1.1.0 开始但低于 1.2.0 的版本。

还有其他的规则：

• 无符号：仅接受指定的特定版本（例如 1.2.1）。
• latest: 使用可用的最新版本。

版本保留

1. 对于大型软件，每个版本都有使用价值时，应保留所有历史版本
2. 对于始终以最新版本为准的软件，则可保留至少最近的 10 个次版本

参考

• Semantic Versioning 2.0.0
• 使用 npm 的语义版本控制

Format

[{emoji} ]{type}[({module})]: {subject within 50 words}[ (#{issue/pull request})]

example:

• 🎉 Feat: add shortcode fixit-encryptor shortcode (#123)
• ⬆️ Chore(libs): update Artalk from 2.2.12 to 2.3.4 (#150)

Emoji

• https://gitmoji.dev
• vscode plugin
• utools plugin GitEmoji

Message

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');

统一用词

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