qingger / allProject

Go to a project
Toggle navigation Toggle navigation pinning
shipfi
5f0340d1 1 parent 5d67aa2f

change mq doc

Inline Side-by-side
Showing 5 changed files with 353 additions and 162 deletions
## 青鸽代码规范 V0.1（整体）
本规范适用于PHP/Javascript/Typescript语言。
所有使用以上语言的项目**必须**遵守此规范，此规范发布后，项目的代码**必须**由项目经理组织全体程序员进行互相Review，不符合规范的代码不得进行提交。
## 产品定义规范
为了促使公司内各产品的衔接，确保各产品之间对接的流畅性。特制定了本规范。
### 1. 产品名称的定义
现在公司内部存在以下几个产品, 各产品统一名称如下：
| 索引 | 英文名称 | 中文名称 | 开发地 |
| ---- | ---- | ---- | ---- |
| 1 | | | 常州 |
## 阿里MNS中Topic发布和订阅规范 v0.1
## 阿里MNS中Topic发布和订阅规范
2017/04/01 : [规范0.1](./V001.md) `此规范从2018/05/15日起废弃`
2018/05/01 : [规范0.2](./V002.md)
本规范基于阿里云的消息服务，所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息，订阅Topic都需要遵循此规范。
---
## 1. 各应用的定义
为了能够让各应用在一个Topic中发布或订阅消息，就需要对各个应用作一个规范的定义。以下是针对现有的产品作出英文名称的定义:
> 因为在Topic中，发布的消息标签最多只能16位字符，而标签的内容包含了应用和业务，所以各应用的英文名称统一的规定在MNS中最多有三位字符。
| 索引 | 产品英文名称 | 产品中文名称 |
| ---- | ------ | ----------------- |
| 1 | SC | Qingger 服务中心 |
| 2 | DZ | Qingger店助产品 |
| 3 | YZ | Qingger云助产品 |
| 4 | ESH | Qingger云商城 |
| 5 | PSH | Qingger积分商城 |
| 6 | B2B | Qingger B2B产品 |
| 7 | POR | Runsa门户 |
| 8 | CRM | Runsa CRM |
| 9 | DRP | Runsa DRP |
| 10 | O2O | Runsa 电商管理平台O2O产品 |
---
## 2. 建立和删除Topic
#### 2.1 建立Topic
- 任何应用如果需要向Topic上发布消息，必须负责建立此Topic的责任（注：多个应用如果需要向一个Topic发布消息，则第一个发布的建立此Topic)
- 任务应用建立Topic并使用其发布消息时，**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
- Topic 命名方法：**{企业编号}-{环境编号}**，表示不同的客户在不同的环境所使用的Topic；
​
- 企业编号： 取和企业有关并且好记的英文名，然后转成大写；
> 例如：星期六的官方英文名是st-sat，因此星期六的企业编号为STSAT
| 企业 | 企业编号 |
| :--- | :---- |
| 星期六 | STSAT |
| 兴记 | XJ |
| 兴记LR | LR |
- 环境编号：
> 使用TEST代表测试环境，DEMO代表演示环境，PROD代表正式环境，DEV代表开发环境。
- 以下为Topic 名称的几个例子：
```
STSAT-TEST：星期六测试用Topic；
STELLAFASHION-PRODUCTION：兴记生产用Topic
```
![](http://of2xnjf2g.bkt.clouddn.com/20170401155704.png)
#### 2.2 删除Topic
- 遵循谁发布谁删除的原则.
---
## 3. 在Topic上发布消息
- 在Topic上发布消息时，消息**必须**标注标签，以便其他应用在收到消息时能够过滤和识别消息类型；
- 标签命名方法：**{应用名称}-{业务名称}**；
* 应用名称：即 **1** 中所列出的产品英文名称；
* 业务名称：根据各应用自己的业务来定义，最多12个字符的大写英文字母；
```
示例：
雇员相关的消息，业务名称可以定义为EMPLOYEE
账户相关的消息，业务名称可以定义为USER
```
- 以下为标签的几个例子：
```
POR-EMPLOYEE ：门户发布的雇员信息
CRM-POINT ：CRM发布的积分信息
```
- 发布消息的消息结构体，各个应用自定义，但是结构体必须发布出gitbook形式，以MD文档进行说明。
![](http://of2xnjf2g.bkt.clouddn.com/20170401155511.png)
---
## 4. 在Topic上订阅消息
#### 4.1 订阅名称
- 订阅名称**建议**命名方法：**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{业务名称}**；
- 环境编号：订阅者环境编号，其值与 **2.1** 中的环境编号一致；
- 订阅者应用或服务名称： **1** 中所列出的产品英文名称，或应用中的各服务模块名称。长度控制在20字符以内。
- 企业编号：与 **2.1** 中的客户编号一致；
- 发布者应用名称：即 **1** 中所列出的产品英文名称；
- 业务名称：与 **3** 中的业务名称一致；
- 以下为订阅名称的几个例子：
```
DEV-YZ-STSAT-POR-EMPLOYEE：云助开发环境订阅了星期六门户发布的雇员消息
PRODUCTION-DZ-STELLAFASHION-CRM-SITE：店助生产环境订阅了兴记CRM发布的网点消息
```
​
#### 4.2 接收端地址
- 推送类型为http或https
- 可以理解为收到推送消息的回调地址，需要各个应用自己开发API接口；
- 为了让回调地址可以最大程度重用，**建议**在创建订阅时在url上带上自己需要的参数；
> http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
以上，http://emp.api.dev.qingger.com 为接口域名，/mns/topic为接口路径，/stsat/por/employee为自定义参数，分别可以帮助各应用确定公司客户，发布者以及业务类型。
![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
​
#### 4.3 重试策略、消息推送格式
- 重试策略：按照需求定义即可
- 消息推送格式：建议使用JSON格式，但是如果为其它格式，则需要应用文档进行说明。
## 版本更新
v0.1 : 2017/04/01 发布此规范
\ No newline at end of file
......
## 阿里MNS中Topic发布和订阅规范 v0.1
本规范基于阿里云的消息服务，所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息，订阅Topic都需要遵循此规范。
---
## 1. 各应用的定义
为了能够让各应用在一个Topic中发布或订阅消息，就需要对各个应用作一个规范的定义。以下是针对现有的产品作出英文名称的定义:
> 因为在Topic中，发布的消息标签最多只能16位字符，而标签的内容包含了应用和业务，所以各应用的英文名称统一的规定在MNS中最多有三位字符。
| 索引 | 产品英文名称 | 产品中文名称 |
| ---- | ------ | ----------------- |
| 1 | SC | Qingger 服务中心 |
| 2 | DZ | Qingger店助产品 |
| 3 | YZ | Qingger云助产品 |
| 4 | ESH | Qingger云商城 |
| 5 | PSH | Qingger积分商城 |
| 6 | B2B | Qingger B2B产品 |
| 7 | POR | Runsa门户 |
| 8 | CRM | Runsa CRM |
| 9 | DRP | Runsa DRP |
| 10 | O2O | Runsa 电商管理平台O2O产品 |
---
## 2. 建立和删除Topic
#### 2.1 建立Topic
- 任何应用如果需要向Topic上发布消息，必须负责建立此Topic的责任（注：多个应用如果需要向一个Topic发布消息，则第一个发布的建立此Topic)
- 任务应用建立Topic并使用其发布消息时，**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
- Topic 命名方法：**{企业编号}-{环境编号}**，表示不同的客户在不同的环境所使用的Topic；
- 企业编号： 取和企业有关并且好记的英文名，然后转成大写；
> 例如：星期六的官方英文名是st-sat，因此星期六的企业编号为STSAT
| 企业 | 企业编号 |
| :--- | :---- |
| 星期六 | STSAT |
| 兴记 | XJ |
| 兴记LR | LR |
- 环境编号：
> 使用TEST代表测试环境，DEMO代表演示环境，PROD代表正式环境，DEV代表开发环境。
- 以下为Topic 名称的几个例子：
```
STSAT-TEST：星期六测试用Topic；
STELLAFASHION-PRODUCTION：兴记生产用Topic
```
![](http://of2xnjf2g.bkt.clouddn.com/20170401155704.png)
#### 2.2 删除Topic
- 遵循谁发布谁删除的原则.
---
## 3. 在Topic上发布消息
- 在Topic上发布消息时，消息**必须**标注标签，以便其他应用在收到消息时能够过滤和识别消息类型；
- 标签命名方法：**{应用名称}-{业务名称}**；
* 应用名称：即 **1** 中所列出的产品英文名称；
* 业务名称：根据各应用自己的业务来定义，最多12个字符的大写英文字母；
```
示例：
雇员相关的消息，业务名称可以定义为EMPLOYEE
账户相关的消息，业务名称可以定义为USER
```
- 以下为标签的几个例子：
```
POR-EMPLOYEE ：门户发布的雇员信息
CRM-POINT ：CRM发布的积分信息
```
- 发布消息的消息结构体，各个应用自定义，但是结构体必须发布出gitbook形式，以MD文档进行说明。
![](http://of2xnjf2g.bkt.clouddn.com/20170401155511.png)
---
## 4. 在Topic上订阅消息
#### 4.1 订阅名称
- 订阅名称**建议**命名方法：**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{业务名称}**；
- 环境编号：订阅者环境编号，其值与 **2.1** 中的环境编号一致；
- 订阅者应用或服务名称： **1** 中所列出的产品英文名称，或应用中的各服务模块名称。长度控制在20字符以内。
- 企业编号：与 **2.1** 中的客户编号一致；
- 发布者应用名称：即 **1** 中所列出的产品英文名称；
- 业务名称：与 **3** 中的业务名称一致；
- 以下为订阅名称的几个例子：
```
DEV-YZ-STSAT-POR-EMPLOYEE：云助开发环境订阅了星期六门户发布的雇员消息
PRODUCTION-DZ-STELLAFASHION-CRM-SITE：店助生产环境订阅了兴记CRM发布的网点消息
```
​
#### 4.2 接收端地址
- 推送类型为http或https
- 可以理解为收到推送消息的回调地址，需要各个应用自己开发API接口；
- 为了让回调地址可以最大程度重用，**建议**在创建订阅时在url上带上自己需要的参数；
> http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
以上，http://emp.api.dev.qingger.com 为接口域名，/mns/topic为接口路径，/stsat/por/employee为自定义参数，分别可以帮助各应用确定公司客户，发布者以及业务类型。
![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
​
#### 4.3 重试策略、消息推送格式
- 重试策略：按照需求定义即可
- 消息推送格式：建议使用JSON格式，但是如果为其它格式，则需要应用文档进行说明。
## 版本更新
v0.1 : 2017/04/01 发布此规范
\ No newline at end of file
## 阿里MNS中Topic发布和订阅规范 v0.2
本规范基于阿里云的消息服务，所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息，订阅Topic都需要遵循此规范。
---
## 1. 业务Topic命名
* 所有在阿里云建立的TOPIC按照 `[应用业务编号]-[ENV]`方式进行命名
* 现应用业务暂时划分为三块 ，环境分为2个，共计6个TOPIC主题订阅
| 索引 | TOPIC名称 | 备注 |
| ---- | --------------- | ------------------------------------------------------------ |
| 1 | QPORTAL-TEST | 主数据测试环境使用的TOPIC |
| 2 | QPORTAL-PROD | 主数据正式环境使用的TOPIC |
| 3 | QMKT-TEST | 营销活动测试环境使用的TOPIC |
| 4 | QMKT-PROD | 营销活动正式环境使用的TOPIC |
| 5 | QINGGER-TEST(*) | 青鸽其它业务(ESHOP, VSHOP, 云货架，图片中心等)测试环境所使用的TOPIC |
| 6 | QINGGER-PROD(*) | 青鸽其它业务(ESHOP, VSHOP, 云货架，图片中心等)正式环境所使用的TOPIC |
备注 : 带*的截至到目前还没有产生具体的消息，在需要消息的时候建立此TOPIC。
​
---
## 2. 建立和删除Topic
#### 2.1 建立Topic
- TOPIC的建立统一由运维人员进行建立 (王志亮/李立俊)。 业务相关方只有使用(发布/订阅)的能力，没有建立的能力。
- 任务应用建立Topic并使用其发布消息时，**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
- Topic 命名方法：**{应用业务编号}-{环境编号}**，所有的客户都共享一个TOPIC.
- 如果客户体量非常大，共用的TOPIC满足不了需求，那么需要向运维人员提出申请，申请批准后，由运维人员向具体开发人员邮件通知。
- TOPIC的使用(发布/订阅)关联的AK/SK由运维邮件通知到各个相关开发/实施人员。
- 环境编号：
> 使用TEST代表测试环境，DEMO代表演示环境，PROD代表正式环境，DEV代表开发环境。
>
> 现在TOPIC中非特殊情况只使用PROD和TEST环境。
#### 2.2 删除Topic
- 当TOPIC不使用时，由运维人员统一删除TOPIC主题。
​
---
## 3. 在Topic上发布消息
- 在Topic上发布消息时，消息**必须**标注标签，以便其他应用在收到消息时能够过滤和识别消息类型；
- **消息标签**命名方法：**{企业集团ID}-{数据业务ID}**；
* 企业集团ID：由发送TOPIC消息业务方命名，但遵循以下几个规则 ：
* 企业编号取企业有关且好记的英文名。
* 企业编号一般使用大写。
* 示例 : STSAT , LR, SHOEM ...
​
* 数据业务ID：根据各应用自己的业务来定义，最多12个字符的大写英文字母；
```
示例：
雇员相关的消息，业务名称可以定义为EMPLOYEE
账户相关的消息，业务名称可以定义为USER
```
- 以下为标签的几个例子：
```
STSAT-EMPLOYEE ：星期六集团下的雇员信息
LR-POINT ：LR集团下的积分信息
```
- 发布消息的消息结构体，一般来说为JSON形式。
- TOPIC消息标签和数据结构定义必须以**文档**形式发布，可供查阅。
---
## 4. 在Topic上订阅消息
#### 4.1 订阅名称
- 订阅名称**建议**命名方法：**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{数据业务ID}**；
- 环境编号：订阅者环境编号，其值与 **2.1** 中的环境编号一致；
- 订阅者应用或服务名称： 订阅者应用的业务名称，由各订阅业务产品定义，如ESHOP, VSHOP,CRM等。
- 业务产品线现包括： ESHOP, VSHOP, YUNOFFLINE, CRM, PORTAL, OMS, WEBSITE等。
- 企业编号：与 **3** 中的客户编号一致；如STSAT, LR等
- 发布者应用名称：即 **1** 中所列出的Topic业务名称，如QPORTAL, QMKT等。
- 业务名称：与 **3** 中的业务名称一致；
- 以下为订阅名称的几个例子：
```
DEV-YZ-STSAT-POR-EMPLOYEE：云助开发环境订阅了星期六门户发布的雇员消息
PRODUCTION-DZ-STELLAFASHION-CRM-SITE：店助生产环境订阅了兴记CRM发布的网点消息
```
​
#### 4.2 接收端地址
- 推送类型为http或https
- 可以理解为收到推送消息的回调地址，需要各个应用自己开发API接口；
- 为了让回调地址可以最大程度重用，**建议**在创建订阅时在url上带上自己需要的参数；
> http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
以上，http://emp.api.dev.qingger.com 为接口域名，/mns/topic为接口路径，/stsat/por/employee为自定义参数，分别可以帮助各应用确定公司客户，发布者以及业务类型。
![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
​
#### 4.3 重试策略、消息推送格式
- 重试策略：按照需求定义即可
- 消息推送格式：建议使用JSON格式，但是如果为其它格式，则需要应用文档进行说明。
## 版本更新
v0.1 : 2017/04/01 发布此规范
v0.2 : 2018/05/01 发布此规范
\ No newline at end of file