Java系统设计规范

1. RestFul API 简介

API（Application Programming Interface） 翻译过来是应用程序编程接口的意思。

RESTful API 可以让你看到 URL+Http Method 就知道这个 URL 是干什么的，让你看到了 HTTP 状态码（status code）就知道请求结果如何。

总结一下什么是 RESTful 架构：

1. 每一个 URI 代表一种资源；
2. 客户端和服务器之间，传递这种资源的某种表现形式比如 json，xml，image,txt 等等；
3. 客户端通过特定的 HTTP 动词，对服务器端资源进行 *** 作，实现"表现层状态转化"。

---

2. RestFul API规范 2.1 动作

• GET：请求从服务器获取特定资源。举个例子：GET /classes（获取所有班级）
• POST ：在服务器上创建一个新的资源。举个例子：POST /classes（创建班级）
• PUT ：更新服务器上的资源（客户端提供更新后的整个资源）。举个例子：PUT /classes/12（更新编号为 12 的班级）
• DELETE ：从服务器删除特定的资源。举个例子：DELETE /classes/12（删除编号为 12 的班级）
• PATCH ：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新），使用的比较少，这里就不举例子了

2.2 接口命名规范

1. 网址中不能有动词，只能有名词，API 中的名词也应该使用复数。 因为 REST 中的资源往往和数据库中的表对应，而数据库中的表都是同种记录的"集合"（collection）。如果 API 调用并不涉及资源（如计算，翻译等 *** 作）的话，可以用动词。比如：GET /calculate?param1=11¶m2=33 。
2. **不用大写字母，建议用中杠 - 不用下杠 _ **。比如邀请码写成 invitation-code而不是 invitation_code 。
3. 善用版本化API。当我们的 API 发生了重大改变而不兼容前期版本的时候，我们可以通过 URL 来实现版本化，比如 http://api.example.com/v1、http://apiv1.example.com。
4. 接口尽量使用名词，避免使用动词。RESTful API *** 作（HTTP Method）的是资源（名词）而不是动作（动词）。

GET    /classes：列出所有班级
POST   /classes：新建一个班级
GET    /classes/{classId}：获取某个指定班级的信息
PUT    /classes/{classId}：更新某个指定班级的信息（一般倾向整体更新）
PATCH  /classes/{classId}：更新某个指定班级的信息（一般倾向部分更新）
DELETE /classes/{classId}：删除某个班级
GET    /classes/{classId}/teachers：列出某个指定班级的所有老师的信息
GET    /classes/{classId}/students：列出某个指定班级的所有学生的信息
DELETE /classes/{classId}/teachers/{ID}：删除某个指定班级下的指定的老师的信息

2.3 过滤信息

如果我们在查询的时候需要添加特定条件的话，建议使用 url 参数的形式。比如我们要查询 state 状态为 active 并且 name 为 guidegege 的班级：

GET    /classes?state=active&name=guidegege

实现分页查询：

GET    /classes?page=1&size=10 //指定第1页，每页10个数据

2.4 状态码

2xx：成功	3xx：重定向	4xx：客户端错误	5xx：服务器错误
200 成功	301 永久重定向	400 错误请求	500 服务器错误
201 创建	304 资源未修改	401 未授权	502 网关错误
		403 禁止访问	504 网关超时
		404 未找到
		405 请求方法不对

---

3. 常见的命名规范

1、类名需要使用大驼峰命名法（UpperCamelCase）风格。比如：ServiceDiscovery、ServiceInstance、LruCacheFactory

2、方法名、参数名、成员变量、局部变量需要使用小驼峰命名法（lowerCamelCase）。

getUserInfo()
createCustomThreadPool()
setNameFormat(String nameFormat)
Uservice userService;

3、测试方法名、常量、枚举名称需要使用蛇形命名法（snake_case），比如should_get_200_status_code_when_request_is_valid、CLIENT_CONNECT_SERVER_FAILURE。并且，测试方法名称要求全部小写，常量以及枚举名称需要全部大写。

4、项目文件夹名称使用串式命名法（kebab-case），比如dubbo-registry。

5、包名统一使用小写，尽量使用单个名词作为包名，各个单词通过 “.” 分隔符连接，并且各个单词必须为单数。比如：org.apache.dubbo.common.threadlocal

6、抽象类命名使用 Abstract 开头。

public abstract class AbstractClient extends AbstractEndpoint implements Client {

}

7、异常类命名使用 Exception 结尾。

//自定义的 NoSuchMethodException（出处：Dubbo源码）
public class NoSuchMethodException extends RuntimeException {
    private static final long serialVersionUID = -2725364246023268766L;

    public NoSuchMethodException() {
        super();
    }

    public NoSuchMethodException(String msg) {
        super(msg);
    }
}

8、测试类命名以它要测试的类的名称开始，以 Test 结尾。

//为 AnnotationUtils 类写的测试类（出处：Dubbo源码）
public class AnnotationUtilsTest {
  ......
}