更新API 错误码

Author: ying.liu

backend/java-code-contract.md

@@ -0,0 +1,139 @@
+# 20180706 代码契约 V0.1 Beta
+
+---
+
+## 1. Spring 依赖注入
+
+- **结论**：绝大部分情况下只使用 Constructor DI，不使用 Field DI
+- **注意事项**：
+  - 使用 Constructor DI 时，若只有一个构造方法，则不用在构造方法上加 @Autowired 注解，且该构造方法形参应只包含要注入的那些依赖
+  - It’s fine to use field based injection in tests when you’re using the SpringJUnit4ClassRunner.
+- **主要原因**：
+  - 如果使用 Field DI，对于 IOC 容器以外的环境，除了使用反射来提供它需要的依赖之外，无法复用该实现类。而且将一直是个潜在的隐患，因为你不调用将一直无法发现 NullPointerException 的存在。
+  - 上文注意事项中提到的 SpringJUnit4ClassRunner 类配合 @Runwith 注解可以让测试在 Spring 容器环境下执行，不会出现标注了 Field DI 的字段未注入的情况。
+- **支撑文章**：[Why field injection is evil](http://olivergierke.de/2013/11/why-field-injection-is-evil/)
+
+## 2. 路由 Router 文件
+
+- **结论**：为保证对外服务的统一管理，将具体的路由信息写在一个统一的文件中，而不是将其拆散写在控制器的每个方法声明头上
+
+## 3. API 返回数据结构及错误代码
+
+应用层与网络层独立，尽量减少全局依赖是 API 设计的一些出发点。最高原则则是用户体验：用户看到最有用的信息。
+
+HTTP Code 是网络层的代码，不要用于反映业务的运行情况。一方面其数量有限，另一方面及其模糊。比如对于错误数据请求： 400 (bad request)、409 (409 Conflict)、 412 (Precondition Failed)、 422(Unprocessable Entity)都在各处使用而且意义不清。Restful 风格的 API 虽然流行，但是要有自己的思考，其更适用于简单的资源 CRUD 场景。而商业系统开发往往是复杂的，不要开始就想着去简化，而应该以系统思维方式处理复杂性。
+
+### 3.1 建议
+
+- HTTP 或任何通讯层协议与业务逻辑/错误处理完全分离。
+- 不用 Restful 错误代码代表业务错误，HTTP code 只用于 HTTP 通讯。
+- 只使用 HTTP POST，所有参数放在 Body， 不用 URL Parameter。
+- 应用运行的状态码由开发人员自己制定和维护。
+- 业务请求参数错误也应该放到业务层而不是网络层（如下面 bing 的例子）。
+- 错误代码/信息的目的是为了给出错误来源，最好能给出用户解决问题的方法（如下面 Bing 的例子）
+
+### 3.2 建议的 API 返回数据结构
+
+```javascript
+{
+    code: number // success 0, business exception starts with 1, system exception starts with 100
+    message: string // message, 'OK' for 0. The message is user-oriented that might be shown to end user.
+    debugMessage?: string // optional, message used for debugging, including request/context data.
+    data?: object // optinal, the biz data, empty if code is not 0
+}
+```
+
+### 3.2 错误代码
+
+- 基本原则: 成功 0, 用户关心的业务错误代码 1 - 99, 其他业务与系统错误代码 >100。
+- 每个 API 方法都有自己定义的 1-99 的业务错误代码，在 API 文档有详细说明。
+- 尽可能用有意义的业务错误代码和信息。常见的例子有：
+  - 某个 API 的一个参数是电话号码， 如果电话号码不合法（比如包含了字符），返回的错误代码应该在 1-99，同时给出 `错误电话号码`信息. `debugMessage`可以给出用户的输入参数和系统的检查信息，比如正则表达式。采用中间件返回 400 (bad request）对用户和 API 使用者没有太大帮助。
+  - 同理，如果用户没有给出一个必须的参数，最好明确指出那个参数缺少 （如下面的 Bing 的例子）。
+- 100 以上的系统错误代码通常由系统中间件处理，可以有一份指导性的标准错误代码。 中间件被各个子系统共享，所以容易标准话。对不关心的系统错误，建议用统一错误代码 500。
+
+### 3.3 他山之石
+
+- **Twitter**：用 HTTP 代码 400 表示所有的商业逻辑错误，同时提供错误细节
+
+```javascript
+{
+    "errors":
+            [{
+                "code":215,
+                "message":"Bad Authentication data."
+            }]
+}
+```
+
+- **Facebook**：用的 GraphQL 风格，HTTP 仅仅是通讯层。错误信息包含了 Exception 的类型和内部调试索引
+
+```javascript
+{
+    "error":{
+        "message": "Syntax error \"Field picture specified more than once. This is only possible before version 2.1\" at character 23: id,name,picture,picture",
+        "type": "OAuthException",
+        "code": 2500,
+        "fbtrace_id": "xxxxxxxxxxx"
+    }
+}
+```
+
+- **Bing**：HTTP 仅仅是通讯层。商业逻辑错误还是用 HTTP 200 状态码。特点是给出了错误的解决答案（哪个参数不对）和请求的后台 URL
+
+```javascript
+HTTP/1.1 200
+{
+    "SearchResponse": {
+        "Version":"2.2",
+        "Query":{
+            "SearchTerms":"api error codes"
+        },
+        "Errors":[{
+            "Code":1001,
+            "Message":"Required parameter is missing.",
+            "Parameter":"SearchRequest.AppId",
+            "HelpUrl":"http\u003a\u002f\u002fmsdn.microsoft.com\u002fen-us\u002flibrary\u002fdd251042.aspx"
+        }]
+    }
+}
+```
+
+### 4. 接口与实现类命名风格
+
+- **结论**
+
+  - 接口名称前不加附属的字母（如接口前加 I），
+  - 实现类后不加附属的无意义单词（如 Impl）
+  - 实现类名相较于接口名后面可加有意义的单词，如 Db
+
+### 5. Pimitive Type or Wrapper Class
+
+- **结论**：
+  - 若该字段可以不初始化，使用 Wrapper Class
+  - 若该字段必须被初始化，使用 Primitive Class
+- **举例**：
+  - Employee 类中的 corpId
+    - 如果员工定义时可以不指定所属公司，则用 Integer
+    - 若定义员工时必须定义公司，则用 int
+
+### 6. 实体类字段不赋默认值
+
+### 7. 方法（Method）风格
+
+- **结论**：过长代码要抽成方法
+
+### 8. 异常的处理
+
+- **结论**：开发应用时，使用两种异常
+  - Java 定义的标准异常，如参数检查中发现 null 参数
+  - 业务相关自定义异常：如密码过长或过短
+    - 自定义异常应继承自 RuntimeException，因为它是 Unchecked Exception
+    - 使用异常类型而非异常信息来分辨异常来自的不同 Domain 类
+- **注意**：以上两个例子即使和你的业务契合，也不一定满足和你的业务要求
+
+### 9. LOG 的等级划分 => 后面提供要求文档（刘博）
+
+- **结论**：
+  - 不要求进出都写，非常短小的的方法不用写，只要能追踪主要参数即可
+  - 数据量太大时打印变量用 Trace，数据量小用 Info

backend/java-code-guideline.md

@@ -1,3 +1,4 @@
-# Java微服务测试框架以及方法
-当前Java服务采用的是Spock进行测试
+# Java 微服务测试框架以及方法
+
+当前 Java 服务采用的是 Spock 进行测试
 具体文档可以参考： http://spockframework.org/