# 关于开发

## 前后端的通信接口规范

## 接口规范和约定 <a href="#id00.-tong-xin-jie-kou-gui-fan-1-jie-kou-gui-fan-he-yue-ding" id="id00.-tong-xin-jie-kou-gui-fan-1-jie-kou-gui-fan-he-yue-ding"></a>

1\. 平台服务端与客户端采用http协议进行通信，客户端向平台服务端发出http请求，服务端获取请求，根据参数执行相关操作，将结果以JSON形式封装返回给客户端。

2\. 在上线后，接口的URL的最后一项前面需要加版本号，版本号从v1 开始后面的数字递增。

```
// 比如初始上线，用户登录的接口应该是这样：
http://xxxx/user/login

// 在维护更新的时候，这个接口需要修改，则需要加上版本号，如：
http://xxxx/user/v1/login
```

{% hint style="success" %}
&#x20; 以避免出现版本升级，用户不更新安装，从而不能继续使用等恶劣情况出现。
{% endhint %}

3\. HTTP Header

| 数据项           | 数据类型   | 备注     |
| ------------- | ------ | ------ |
| Authorization | String | 用于用户鉴权 |

{% hint style="info" %}
具体业务流程，设计具体的逻辑。
{% endhint %}

4\. 请求约定

> &#x20;请求报文以JSON格式进行传递

5\. 响应约定

> &#x20;数据JSON格式返回。JSON对象结构如下：

```javascript
// 默认返回状态码 200
{
    code: "SUCCESS",  // 有四种类型： SUCCESS、BIZ、AUTH、SYS
    data: {},         // 返回的数据，类型不限
    msg: "",          // 返回的信息
    meta: {}          // 其他数据，譬如分页数据
}
```

{% hint style="info" %}
code 的四种类型分别对应：

1. SUCCESS：成功
2. BIZ：业务逻辑错误
3. AUTH：鉴权失败
4. SYS：系统错误

msg：在请求返回的code除了SUCCESS之外，均会带上请求响应返回的错误信息，提示用户发生了什么
{% endhint %}

## Git 版本管理

一个优秀的产品需要稳定的迭代与更新，因此需要规范的源码管理。

![Git Flow](https://242152934-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLomM1BXeaSOPDNrd8S%2F-LLp75keiRmoe7kh9Jwj%2F-LLpN9dDsnFmarxHmu17%2Fgitflow.png?alt=media\&token=779065fc-4ea7-4d93-b1e8-164608535cbd)

1. 主要分支介绍

   1. master分支（禁止直接push）主分支，产品的功能全部实现后，最终在master分支对外发布。
   2. dev分支（禁止直接push）测试分支，基于master分支克隆，产品编码工作完成后，发布到本分支测试。
   3. hotfix分支 当生产环境发现严重且必须马上解决的bug时，基于master创建并在本分支修复后，合并到master和dev。本分支属于临时分支，目的实现后可删除分支。
   4. 个人本地dev分支（禁止直接commit，下称local-dev分支）本地分支，基于dev分支克隆。
   5. 个人本地feature分支（下称local-feature分支）本地分支，基于master分支克隆。

2. 分支命名规范

   建议本地分支命名与远程分支保存一致。\_\_- \_\_分支名只允许使用小写字母（a-z）或数字（0-9）或 - 或 / ，其余字符（包括但不限于 \_ \* + @ # $）一律禁止使用.

   1. 本地dev分支push到远程的分支名

      命名空间（你名字缩写）/分支名   如：lzy/dev

3. PR规范

   1. 创建PR 中英文不限，但标题与内容保持一致
   2. &#x20;标题（必填）- \_\_必须\_\_以 \_\_【PR】\_\_ 或者 \_\_【HF】\_\_ 开头，后面跟着该PR主要功能的概要（50字内）。【PR】：一般的功能【HF】：严重且必须马上解决的bug的修复
   3. &#x20;内容（可选） - 该PR主要功能的相对详细描述（100字内）。
   4. &#x20;标签（必选）- 视基准分支（即代码合入的分支）的不同，选择“正式版”或“测试版”。
   5. &#x20;指派成员（必选）- （不能选择自己）选择另一个团队成员进行 code review。

4. 合并PR

   1. 被指派 code review 的人务必认真审核，合并后主动删除对比分支
   2. 审核代码内容是否跟 PR 标题保持一致
   3. 检查PR基准分支（dev）跟对比分支（lzy/dev）
   4. 检查是否在 push 之前有 pull 的 commit （如该 PR 是将 lzy/dev 合并到 dev，则必须要有 \_\_Merge branch 'dev' of XXX into lzy/dev\_\_ 的 commit ）

5. 发布
   1. 基于 master 分支打 release tag，生产服 checkout 到最新且稳定的 tag
   2. tag规范。以release开头，后面跟着当前年月日（共8位）和流水号。如：release-20180321-06

{% hint style="info" %}
开发流程： {本地测试通过} -->{内测版测试通过} --> {体验版测试通过} --> {发布}
{% endhint %}
