Rules

+## 开发文档规范
+
+### 1. 概要 
+
+* 公司中，开发文档全部使用md文件，上传到项目对应的Gitlab中。
+* 文档写作辅助工具包括:
+  * Typora / MarkdownPro :  MD文档撰写工具
+  * XMind : 思维导图工具
+  * Visio : 流程图工具
+* 任何一个项目，以下文档不可缺，且随着开发的不断进行，也需要不断的更新
+  * API接口文档 及 API接口特别说明文档
+  * 数据库文档
+  * 与其它系统交互的系统交互文档
+  * 功能复杂的流程图
+  * 代码文件的phpDoc文档
+
+
+
+---
+
+
+
+### 2.API文档 
+
+#### 2.1 API文档做成约定
+
+API文档默认放在各项目 S2_Project | P1_API 目录下。此目录定义了暴露给外部应用的每个接口的参数和返回值。
+
+在写API文档时，规约包含以下几个方面:
+
+* 各个API必须以独一的形式进行编号。
+
+* 每个API文档必须定义版本，在应用层上的版本和API文档的版本必须一致。
+
+* API文档必须给出地址的PATH路径值。
+
+* API文档必须给出调用的HTTP方法: GET | POST | DELETE | PUT
+
+* API文档必须给出应答的格式，默认为JSON
+
+* API的请求参数必须要详细说明，说明包括: 
+
+  > 类型 / 是否必须 / 备注
+  >
+  > 如果参数不同，带来的返回值有很大的差异，在需要说明的情况下，也必须落实成文档。
+
+* API的返回值的参数也必须要详细说明。说明包括:
+
+  > 返回示例，返回各数据的类型， 返回各数据的详细说明。
+
+* 如果有些返回值是可选的，也需要给出说明。
+
+* 每个API文档下方必须要存在更新备注信息。当每一次更新API，除了修改文档，也在下方写明备注原因。
+
+* 因升级，过时的API必须标注为depreciated.
+
+* 如果此API依赖于其它的系统交互，需要给出其它系统流程的文档跳转地址。
+
+* 对于复杂的API（如用户验证、支付、订单流转等），需要额外定义文档，
+

@@ -103,7 +103,7 @@
   }
   }
   ```
   ```
 
 
-* Controller通过调用Model层，自定义Service层，Event, Queue来完成自身的业务逻辑。但是在Controller层，尽量做到对于底层服务的底耦合，为了能够更好的测度，也尽量使用对象的依赖注入。
+* Controller通过调用Model层，自定义Service层，Event, Queue来完成自身的业务逻辑。但是在Controller层，尽量做到对于底层服务的底耦合，为了能够更好的测试，也尽量使用对象的依赖注入。
 
 
 * Controller层与其它层的一般关系如下
 * Controller层与其它层的一般关系如下
 
 

@@ -7,7 +7,7 @@
 
 
 * 对于各个表的Model, 继承自定义的BaseModel类，而不是Model类
 * 对于各个表的Model, 继承自定义的BaseModel类，而不是Model类
 
 
-* 如果表和表之间有一定的关系，1vs1, 1vsN，那在Model中使用hasOne,belongsTo进行映射，通过这样的映射，可以对Model对象实现很清晰的操作逻辑:
+* 如果表和表之间有一定的关系，1vs1, 1vsN，那在Model中使用hasOne,belongsTo,hasMany进行映射，通过这样的映射，可以对Model对象实现很清晰的操作逻辑:
 
 
 ```php
 ```php
 class GroupModel extends BaseModel {
 class GroupModel extends BaseModel {
@@ -50,7 +50,6 @@ $groupInstance = (new GroupModel())->getInstanceByGroupCode('Foo');
 $groupWeixinInfoInstance = $groupInstance->myWeixinGroupInfo();
 $groupWeixinInfoInstance = $groupInstance->myWeixinGroupInfo();
 $groupSites = $groupInstance->myGroupSites()->filter( function($site) {/**/ });
 $groupSites = $groupInstance->myGroupSites()->filter( function($site) {/**/ });
 
 
-
 ```
 ```
 
 
 * Model必须实现数据表的增删改操作，不能让这些操作暴露在Controller或者Service中
 * Model必须实现数据表的增删改操作，不能让这些操作暴露在Controller或者Service中
@@ -92,19 +91,19 @@ public function insertUser(array $userInfo) {
 
 
 * 不要使用scope类型的函数。
 * 不要使用scope类型的函数。
 
 
-* 在函数上区分并辩明属于Model的方法和属于Instance的方法。
+* 在函数上区分并辩明属于Model对象的方法和属于Instance对象的方法。
 
 
-  > 所谓Model方法，是指new一个Model实例即可调用的方法，对于操作库，可以使用Model方法
+  > 所谓Model对象的方法，是指new一个Model实例即可调用的方法，对于操作库，可以使用Model方法
   >
   >
-  > 所谓Instance方法，是指对应的数据表中的一个实例，例如，通过User::find(1)即可获得一个Instance方法。
+  > 所谓Instance对象可调用的方法，是指对应的数据表中的一个实例，例如，通过User::find(1)即可获得一个Instance对象。
   >
   >
   > Instance方法一般用来获得属性，实现实例的业务逻辑，操作与此实例关联的其它数据模型的实例。
   > Instance方法一般用来获得属性，实现实例的业务逻辑，操作与此实例关联的其它数据模型的实例。
   >
   >
   > 一般来说，在Instance方法上，加一个My修饰词进行表示。
   > 一般来说，在Instance方法上，加一个My修饰词进行表示。
 
 
 ```php
 ```php
-public function insertUser(array $userInfo);  // Model方法
-public function getMyUserName() { return $this->user_name; } // Instance方法
+public function insertUser(array $userInfo);  // Model对象的方法
+public function getMyUserName() { return $this->user_name; } // Instance对象的方法
 public function checkMyRoles() { /**/ }
 public function checkMyRoles() { /**/ }
 ```
 ```
 
 

@@ -105,7 +105,7 @@
   define('CURRENT_SCRIPT','index_php');
   define('CURRENT_SCRIPT','index_php');
   const TRANSCATION_TYPE = 'income';
   const TRANSCATION_TYPE = 'income';
 
 
-  // 私有变量(protected不在此列)
+  // 私有变量
   private $orderCnt = 0;
   private $orderCnt = 0;
   protected $salaryAmount = 0;
   protected $salaryAmount = 0;
 
 
@@ -133,7 +133,6 @@
 * 自编写的类一般遵循名词或名词短语来进行命名。
 * 自编写的类一般遵循名词或名词短语来进行命名。
 * 类的动作方法 ，一般使用【动词+名词】方式进行命名，例如 sendMessage / getAttr / setAttr / postLogin等
 * 类的动作方法 ，一般使用【动词+名词】方式进行命名，例如 sendMessage / getAttr / setAttr / postLogin等
 * 类的属性和变量字段，使用小写字母或者小写驼峰方式命名
 * 类的属性和变量字段，使用小写字母或者小写驼峰方式命名
-* 类的private字段和方法，**必须**使用带_前缀的方式命名
 * 常量值，统一使用大写。
 * 常量值，统一使用大写。
 * 如果方法为API由外部调用，不允许修改方法签名，避免对接口调用方产生影响。
 * 如果方法为API由外部调用，不允许修改方法签名，避免对接口调用方产生影响。
 * 所有继承的覆写方法，必须加@Override 注解
 * 所有继承的覆写方法，必须加@Override 注解
@@ -151,7 +150,7 @@
 
 
 * 所有的类、函数、方法定义都需要进行注释。
 * 所有的类、函数、方法定义都需要进行注释。
 
 
-* 类、方法、函数统一使用/** 内容 */ 注释格式， 不得使用 //** 方式
+* 类、方法、函数统一使用/** 内容 */ 注释格式， 不得使用 // 方式
 
 
 * 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
 * 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
 
 
@@ -294,8 +293,6 @@
   method('a', 'b', 'c');
   method('a', 'b', 'c');
   ```
   ```
 
 
-  ?
-
 * 在类中（尤其是在Model)，对于每个属性的访问, 统一使用get/set方法
 * 在类中（尤其是在Model)，对于每个属性的访问, 统一使用get/set方法
 
 
   ```php
   ```php
@@ -363,7 +360,7 @@
   }
   }
   ```
   ```
 
 
-* 代码做到复用，对于相同听代码逻辑，严禁出现在两个函数或者两个文件内，如果逻辑相同，使用重构提取共用性。必要时抽取共性方法，或者抽象公共类，甚至是共用模块。
+* 代码做到复用，对于相同的代码逻辑，严禁出现在两个函数或者两个文件内，如果逻辑相同，使用重构提取共用性。必要时抽取共性方法，或者抽象公共类，甚至是共用模块。
 
 
 * 一个函数的逻辑实现**严禁**超过一屏（非常特殊或者逻辑简单可理解的除外）。如果业务复杂，使用多个函数实现。
 * 一个函数的逻辑实现**严禁**超过一屏（非常特殊或者逻辑简单可理解的除外）。如果业务复杂，使用多个函数实现。
 
 
@@ -377,8 +374,6 @@
   if ($existed) { /*...*/ }  
   if ($existed) { /*...*/ }  
   ```
   ```
 
 
-  ?
-
 * 一个函数中**不能**出现以下复杂的if/else逻辑判断,  一个规则，每个函数只if/elseif/else嵌套不超过三层。
 * 一个函数中**不能**出现以下复杂的if/else逻辑判断,  一个规则，每个函数只if/elseif/else嵌套不超过三层。
 
 
 * 逻辑上超过 3 层的 if-else 代码可以使用卫语句或状态模式来实现，关于 [卫语句](http://blog.csdn.net/jw903/article/details/45506777)。
 * 逻辑上超过 3 层的 if-else 代码可以使用卫语句或状态模式来实现，关于 [卫语句](http://blog.csdn.net/jw903/article/details/45506777)。
@@ -445,7 +440,6 @@
   foreach($items as $key=>$item) {
   foreach($items as $key=>$item) {
     // do sth
     // do sth
   }
   }
-
   ```
   ```
 
 
   ?
   ?
@@ -469,7 +463,6 @@
 * 注意日志输出的级别，error 级别只记录系统逻辑出错、异常等重要的错误信息。
 * 注意日志输出的级别，error 级别只记录系统逻辑出错、异常等重要的错误信息。
 
 
 
 
-
 ---
 ---
 
 
 
 
@@ -482,7 +475,6 @@
 * 在应用代码中使用“抛异常”代替“返回错误码”，应用如果是API，则对异常作出处理，返回匹配的Result结果信息。
 * 在应用代码中使用“抛异常”代替“返回错误码”，应用如果是API，则对异常作出处理，返回匹配的Result结果信息。
 
 
 
 
-
 ---
 ---
 
 
 
 
@@ -497,3 +489,4 @@
   ![](http://of2xnjf2g.bkt.clouddn.com/20170329172942.png)
   ![](http://of2xnjf2g.bkt.clouddn.com/20170329172942.png)
 
 
   ?
   ?
+