shipfi

change mq doc

1 +## 青鸽代码规范 V0.1(整体)
2 +
3 +
4 +
5 +本规范适用于PHP/Javascript/Typescript语言。
6 +
7 +所有使用以上语言的项目**必须**遵守此规范,此规范发布后,项目的代码**必须**由项目经理组织全体程序员进行互相Review,不符合规范的代码不得进行提交。
8 +
1 +## 产品定义规范
2 +
3 +为了促使公司内各产品的衔接,确保各产品之间对接的流畅性。特制定了本规范。
4 +
5 +
6 +
7 +### 1. 产品名称的定义
8 +
9 +现在公司内部存在以下几个产品, 各产品统一名称如下:
10 +
11 +| 索引 | 英文名称 | 中文名称 | 开发地 |
12 +| ---- | ---- | ---- | ---- |
13 +| 1 | | | 常州 |
14 +
1 -## 阿里MNS中Topic发布和订阅规范 v0.1 1 +## 阿里MNS中Topic发布和订阅规范
2 2
3 +2017/04/01 : [规范0.1](./V001.md) `此规范从2018/05/15日起废弃`
3 4
5 +2018/05/01 : [规范0.2](./V002.md)
4 6
5 -本规范基于阿里云的消息服务,所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息,订阅Topic都需要遵循此规范。
6 7
7 8
8 -
9 ----
10 -
11 -## 1. 各应用的定义
12 -
13 -为了能够让各应用在一个Topic中发布或订阅消息,就需要对各个应用作一个规范的定义。以下是针对现有的产品作出英文名称的定义:
14 -
15 -> 因为在Topic中,发布的消息标签最多只能16位字符,而标签的内容包含了应用和业务,所以各应用的英文名称统一的规定在MNS中最多有三位字符。
16 -
17 -| 索引 | 产品英文名称 | 产品中文名称 |
18 -| ---- | ------ | ----------------- |
19 -| 1 | SC | Qingger 服务中心 |
20 -| 2 | DZ | Qingger店助产品 |
21 -| 3 | YZ | Qingger云助产品 |
22 -| 4 | ESH | Qingger云商城 |
23 -| 5 | PSH | Qingger积分商城 |
24 -| 6 | B2B | Qingger B2B产品 |
25 -| 7 | POR | Runsa门户 |
26 -| 8 | CRM | Runsa CRM |
27 -| 9 | DRP | Runsa DRP |
28 -| 10 | O2O | Runsa 电商管理平台O2O产品 |
29 -
30 -
31 ----
32 -
33 -## 2. 建立和删除Topic
34 -
35 -#### 2.1 建立Topic
36 -
37 -- 任何应用如果需要向Topic上发布消息,必须负责建立此Topic的责任(注:多个应用如果需要向一个Topic发布消息,则第一个发布的建立此Topic)
38 -
39 -- 任务应用建立Topic并使用其发布消息时,**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
40 -
41 -- Topic 命名方法:**{企业编号}-{环境编号}**,表示不同的客户在不同的环境所使用的Topic;
42 -
43 -
44 -
45 -- 企业编号: 取和企业有关并且好记的英文名,然后转成大写;
46 -
47 - > 例如:星期六的官方英文名是st-sat,因此星期六的企业编号为STSAT
48 -
49 -
50 -| 企业 | 企业编号 |
51 -| :--- | :---- |
52 -| 星期六 | STSAT |
53 -| 兴记 | XJ |
54 -| 兴记LR | LR |
55 -
56 -
57 -- 环境编号:
58 -
59 - > 使用TEST代表测试环境,DEMO代表演示环境,PROD代表正式环境,DEV代表开发环境。
60 -
61 -- 以下为Topic 名称的几个例子:
62 -
63 - ```
64 - STSAT-TEST:星期六测试用Topic;
65 - STELLAFASHION-PRODUCTION:兴记生产用Topic
66 - ```
67 -
68 -![](http://of2xnjf2g.bkt.clouddn.com/20170401155704.png)
69 -
70 -
71 -#### 2.2 删除Topic
72 -
73 -- 遵循谁发布谁删除的原则.
74 -
75 -
76 -
77 ----
78 -
79 -
80 -
81 -## 3. 在Topic上发布消息
82 -
83 -- 在Topic上发布消息时,消息**必须**标注标签,以便其他应用在收到消息时能够过滤和识别消息类型;
84 -
85 -- 标签命名方法:**{应用名称}-{业务名称}**;
86 -
87 - * 应用名称:即 **1** 中所列出的产品英文名称;
88 -
89 - * 业务名称:根据各应用自己的业务来定义,最多12个字符的大写英文字母;
90 -
91 - ```
92 - 示例:
93 - 雇员相关的消息,业务名称可以定义为EMPLOYEE
94 - 账户相关的消息,业务名称可以定义为USER
95 - ```
96 -
97 -- 以下为标签的几个例子:
98 -
99 - ```
100 - POR-EMPLOYEE :门户发布的雇员信息
101 - CRM-POINT :CRM发布的积分信息
102 - ```
103 -
104 -- 发布消息的消息结构体,各个应用自定义,但是结构体必须发布出gitbook形式,以MD文档进行说明。
105 -
106 -![](http://of2xnjf2g.bkt.clouddn.com/20170401155511.png)
107 -
108 -
109 ----
110 -
111 -
112 -
113 -## 4. 在Topic上订阅消息
114 -
115 -#### 4.1 订阅名称
116 -
117 -- 订阅名称**建议**命名方法:**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{业务名称}**
118 -
119 -- 环境编号:订阅者环境编号,其值与 **2.1** 中的环境编号一致;
120 -
121 -- 订阅者应用或服务名称: **1** 中所列出的产品英文名称,或应用中的各服务模块名称。长度控制在20字符以内。
122 -
123 -- 企业编号:与 **2.1** 中的客户编号一致;
124 -
125 -- 发布者应用名称:即 **1** 中所列出的产品英文名称;
126 -
127 -- 业务名称:与 **3** 中的业务名称一致;
128 -
129 -- 以下为订阅名称的几个例子:
130 -
131 - ```
132 - DEV-YZ-STSAT-POR-EMPLOYEE:云助开发环境订阅了星期六门户发布的雇员消息
133 - PRODUCTION-DZ-STELLAFASHION-CRM-SITE:店助生产环境订阅了兴记CRM发布的网点消息
134 - ```
135 -
136 -
137 -
138 -#### 4.2 接收端地址
139 -
140 -- 推送类型为http或https
141 -
142 -
143 -- 可以理解为收到推送消息的回调地址,需要各个应用自己开发API接口;
144 -
145 -- 为了让回调地址可以最大程度重用,**建议**在创建订阅时在url上带上自己需要的参数;
146 -
147 - > http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
148 -
149 - 以上,http://emp.api.dev.qingger.com 为接口域名,/mns/topic为接口路径,/stsat/por/employee为自定义参数,分别可以帮助各应用确定公司客户,发布者以及业务类型。
150 -
151 -
152 -![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
153 -
154 -
155 -
156 -#### 4.3 重试策略、消息推送格式
157 -
158 -- 重试策略:按照需求定义即可
159 -- 消息推送格式:建议使用JSON格式,但是如果为其它格式,则需要应用文档进行说明。
160 -
161 -
162 -
163 -
164 -
165 -## 版本更新
166 -
167 -v0.1 : 2017/04/01 发布此规范
...\ No newline at end of file ...\ No newline at end of file
......
1 +## 阿里MNS中Topic发布和订阅规范 v0.1
2 +
3 +
4 +
5 +本规范基于阿里云的消息服务,所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息,订阅Topic都需要遵循此规范。
6 +
7 +
8 +
9 +---
10 +
11 +## 1. 各应用的定义
12 +
13 +为了能够让各应用在一个Topic中发布或订阅消息,就需要对各个应用作一个规范的定义。以下是针对现有的产品作出英文名称的定义:
14 +
15 +> 因为在Topic中,发布的消息标签最多只能16位字符,而标签的内容包含了应用和业务,所以各应用的英文名称统一的规定在MNS中最多有三位字符。
16 +
17 +| 索引 | 产品英文名称 | 产品中文名称 |
18 +| ---- | ------ | ----------------- |
19 +| 1 | SC | Qingger 服务中心 |
20 +| 2 | DZ | Qingger店助产品 |
21 +| 3 | YZ | Qingger云助产品 |
22 +| 4 | ESH | Qingger云商城 |
23 +| 5 | PSH | Qingger积分商城 |
24 +| 6 | B2B | Qingger B2B产品 |
25 +| 7 | POR | Runsa门户 |
26 +| 8 | CRM | Runsa CRM |
27 +| 9 | DRP | Runsa DRP |
28 +| 10 | O2O | Runsa 电商管理平台O2O产品 |
29 +
30 +---
31 +
32 +## 2. 建立和删除Topic
33 +
34 +#### 2.1 建立Topic
35 +
36 +- 任何应用如果需要向Topic上发布消息,必须负责建立此Topic的责任(注:多个应用如果需要向一个Topic发布消息,则第一个发布的建立此Topic)
37 +
38 +- 任务应用建立Topic并使用其发布消息时,**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
39 +
40 +- Topic 命名方法:**{企业编号}-{环境编号}**,表示不同的客户在不同的环境所使用的Topic;
41 +
42 +- 企业编号: 取和企业有关并且好记的英文名,然后转成大写;
43 +
44 + > 例如:星期六的官方英文名是st-sat,因此星期六的企业编号为STSAT
45 +
46 +
47 +| 企业 | 企业编号 |
48 +| :--- | :---- |
49 +| 星期六 | STSAT |
50 +| 兴记 | XJ |
51 +| 兴记LR | LR |
52 +
53 +
54 +- 环境编号:
55 +
56 + > 使用TEST代表测试环境,DEMO代表演示环境,PROD代表正式环境,DEV代表开发环境。
57 +
58 +- 以下为Topic 名称的几个例子:
59 +
60 + ```
61 + STSAT-TEST:星期六测试用Topic;
62 + STELLAFASHION-PRODUCTION:兴记生产用Topic
63 + ```
64 +
65 +![](http://of2xnjf2g.bkt.clouddn.com/20170401155704.png)
66 +
67 +
68 +#### 2.2 删除Topic
69 +
70 +- 遵循谁发布谁删除的原则.
71 +
72 +
73 +---
74 +
75 +
76 +
77 +## 3. 在Topic上发布消息
78 +
79 +- 在Topic上发布消息时,消息**必须**标注标签,以便其他应用在收到消息时能够过滤和识别消息类型;
80 +
81 +- 标签命名方法:**{应用名称}-{业务名称}**;
82 +
83 + * 应用名称:即 **1** 中所列出的产品英文名称;
84 +
85 + * 业务名称:根据各应用自己的业务来定义,最多12个字符的大写英文字母;
86 +
87 + ```
88 + 示例:
89 + 雇员相关的消息,业务名称可以定义为EMPLOYEE
90 + 账户相关的消息,业务名称可以定义为USER
91 + ```
92 +
93 +- 以下为标签的几个例子:
94 +
95 + ```
96 + POR-EMPLOYEE :门户发布的雇员信息
97 + CRM-POINT :CRM发布的积分信息
98 + ```
99 +
100 +- 发布消息的消息结构体,各个应用自定义,但是结构体必须发布出gitbook形式,以MD文档进行说明。
101 +
102 +![](http://of2xnjf2g.bkt.clouddn.com/20170401155511.png)
103 +
104 +---
105 +
106 +
107 +
108 +## 4. 在Topic上订阅消息
109 +
110 +#### 4.1 订阅名称
111 +
112 +- 订阅名称**建议**命名方法:**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{业务名称}**
113 +
114 +- 环境编号:订阅者环境编号,其值与 **2.1** 中的环境编号一致;
115 +
116 +- 订阅者应用或服务名称: **1** 中所列出的产品英文名称,或应用中的各服务模块名称。长度控制在20字符以内。
117 +
118 +- 企业编号:与 **2.1** 中的客户编号一致;
119 +
120 +- 发布者应用名称:即 **1** 中所列出的产品英文名称;
121 +
122 +- 业务名称:与 **3** 中的业务名称一致;
123 +
124 +- 以下为订阅名称的几个例子:
125 +
126 + ```
127 + DEV-YZ-STSAT-POR-EMPLOYEE:云助开发环境订阅了星期六门户发布的雇员消息
128 + PRODUCTION-DZ-STELLAFASHION-CRM-SITE:店助生产环境订阅了兴记CRM发布的网点消息
129 + ```
130 +
131 +
132 +
133 +#### 4.2 接收端地址
134 +
135 +- 推送类型为http或https
136 +
137 +
138 +- 可以理解为收到推送消息的回调地址,需要各个应用自己开发API接口;
139 +
140 +- 为了让回调地址可以最大程度重用,**建议**在创建订阅时在url上带上自己需要的参数;
141 +
142 + > http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
143 +
144 + 以上,http://emp.api.dev.qingger.com 为接口域名,/mns/topic为接口路径,/stsat/por/employee为自定义参数,分别可以帮助各应用确定公司客户,发布者以及业务类型。
145 +
146 +
147 +![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
148 +
149 +
150 +
151 +#### 4.3 重试策略、消息推送格式
152 +
153 +- 重试策略:按照需求定义即可
154 +- 消息推送格式:建议使用JSON格式,但是如果为其它格式,则需要应用文档进行说明。
155 +
156 +
157 +
158 +
159 +
160 +## 版本更新
161 +
162 +v0.1 : 2017/04/01 发布此规范
...\ No newline at end of file ...\ No newline at end of file
1 +## 阿里MNS中Topic发布和订阅规范 v0.2
2 +
3 +
4 +
5 +本规范基于阿里云的消息服务,所有的Qingger/Runsa应用如果需要在MNS上面建立Topic, 在Topic中发布消息,订阅Topic都需要遵循此规范。
6 +
7 +
8 +
9 +---
10 +
11 +## 1. 业务Topic命名
12 +
13 +* 所有在阿里云建立的TOPIC按照 `[应用业务编号]-[ENV]`方式进行命名
14 +* 现应用业务暂时划分为三块 ,环境分为2个,共计6个TOPIC主题订阅
15 +
16 +| 索引 | TOPIC名称 | 备注 |
17 +| ---- | --------------- | ------------------------------------------------------------ |
18 +| 1 | QPORTAL-TEST | 主数据测试环境使用的TOPIC |
19 +| 2 | QPORTAL-PROD | 主数据正式环境使用的TOPIC |
20 +| 3 | QMKT-TEST | 营销活动测试环境使用的TOPIC |
21 +| 4 | QMKT-PROD | 营销活动正式环境使用的TOPIC |
22 +| 5 | QINGGER-TEST(*) | 青鸽其它业务(ESHOP, VSHOP, 云货架,图片中心等)测试环境所使用的TOPIC |
23 +| 6 | QINGGER-PROD(*) | 青鸽其它业务(ESHOP, VSHOP, 云货架,图片中心等)正式环境所使用的TOPIC |
24 +
25 +注 : 带*的截至到目前还没有产生具体的消息,在需要消息的时候建立此TOPIC。
26 +
27 +
28 +
29 +
30 +
31 +---
32 +
33 +## 2. 建立和删除Topic
34 +
35 +#### 2.1 建立Topic
36 +
37 +- TOPIC的建立统一由运维人员进行建立 (王志亮/李立俊)。 业务相关方只有使用(发布/订阅)的能力,没有建立的能力。
38 +- 任务应用建立Topic并使用其发布消息时,**必须**编写相关文档并说明消息的业务类型、消息体的结构说明和示例。
39 +- Topic 命名方法:**{应用业务编号}-{环境编号}**,所有的客户都共享一个TOPIC.
40 +- 如果客户体量非常大,共用的TOPIC满足不了需求,那么需要向运维人员提出申请,申请批准后,由运维人员向具体开发人员邮件通知。
41 +- TOPIC的使用(发布/订阅)关联的AK/SK由运维邮件通知到各个相关开发/实施人员。
42 +
43 +
44 +
45 +- 环境编号:
46 +
47 + > 使用TEST代表测试环境,DEMO代表演示环境,PROD代表正式环境,DEV代表开发环境。
48 + >
49 + > 现在TOPIC中非特殊情况只使用PROD和TEST环境。
50 +
51 +
52 +
53 +
54 +#### 2.2 删除Topic
55 +
56 +- 当TOPIC不使用时,由运维人员统一删除TOPIC主题。
57 +
58 +
59 +
60 +
61 +
62 +
63 +---
64 +
65 +
66 +
67 +## 3. 在Topic上发布消息
68 +
69 +- 在Topic上发布消息时,消息**必须**标注标签,以便其他应用在收到消息时能够过滤和识别消息类型;
70 +
71 +- **消息标签**命名方法:**{企业集团ID}-{数据业务ID}**;
72 +
73 + * 企业集团ID:由发送TOPIC消息业务方命名,但遵循以下几个规则 :
74 +
75 + * 企业编号取企业有关且好记的英文名。
76 + * 企业编号一般使用大写。
77 + * 示例 : STSAT , LR, SHOEM ...
78 +
79 +
80 +
81 + * 数据业务ID:根据各应用自己的业务来定义,最多12个字符的大写英文字母;
82 +
83 + ```
84 + 示例:
85 + 雇员相关的消息,业务名称可以定义为EMPLOYEE
86 + 账户相关的消息,业务名称可以定义为USER
87 + ```
88 +
89 +
90 +
91 +- 以下为标签的几个例子:
92 +
93 + ```
94 + STSAT-EMPLOYEE :星期六集团下的雇员信息
95 + LR-POINT :LR集团下的积分信息
96 + ```
97 +
98 +- 发布消息的消息结构体,一般来说为JSON形式。
99 +
100 +- TOPIC消息标签和数据结构定义必须以**文档**形式发布,可供查阅。
101 +
102 +
103 +
104 +---
105 +
106 +
107 +
108 +## 4. 在Topic上订阅消息
109 +
110 +#### 4.1 订阅名称
111 +
112 +- 订阅名称**建议**命名方法:**{环境编号}-{订阅者应用名称}-{企业编号}-{发布者应用名称}-{数据业务ID}**
113 +
114 +- 环境编号:订阅者环境编号,其值与 **2.1** 中的环境编号一致;
115 +
116 +- 订阅者应用或服务名称: 订阅者应用的业务名称,由各订阅业务产品定义,如ESHOP, VSHOP,CRM等。
117 +
118 + - 业务产品线现包括: ESHOP, VSHOP, YUNOFFLINE, CRM, PORTAL, OMS, WEBSITE等。
119 +
120 +- 企业编号:与 **3** 中的客户编号一致;如STSAT, LR等
121 +
122 +- 发布者应用名称:即 **1** 中所列出的Topic业务名称,如QPORTAL, QMKT等。
123 +
124 +- 业务名称:与 **3** 中的业务名称一致;
125 +
126 +- 以下为订阅名称的几个例子:
127 +
128 + ```
129 + DEV-YZ-STSAT-POR-EMPLOYEE:云助开发环境订阅了星期六门户发布的雇员消息
130 + PRODUCTION-DZ-STELLAFASHION-CRM-SITE:店助生产环境订阅了兴记CRM发布的网点消息
131 + ```
132 +
133 +
134 +
135 +#### 4.2 接收端地址
136 +
137 +- 推送类型为http或https
138 +
139 +
140 +- 可以理解为收到推送消息的回调地址,需要各个应用自己开发API接口;
141 +
142 +- 为了让回调地址可以最大程度重用,**建议**在创建订阅时在url上带上自己需要的参数;
143 +
144 + > http://emp.api.dev.qingger.com/mns/topic/stsat/por/employee
145 +
146 + 以上,http://emp.api.dev.qingger.com 为接口域名,/mns/topic为接口路径,/stsat/por/employee为自定义参数,分别可以帮助各应用确定公司客户,发布者以及业务类型。
147 +
148 +
149 +![](http://of2xnjf2g.bkt.clouddn.com/20170401155826.png)
150 +
151 +
152 +
153 +#### 4.3 重试策略、消息推送格式
154 +
155 +- 重试策略:按照需求定义即可
156 +- 消息推送格式:建议使用JSON格式,但是如果为其它格式,则需要应用文档进行说明。
157 +
158 +
159 +
160 +
161 +
162 +## 版本更新
163 +
164 +v0.1 : 2017/04/01 发布此规范
165 +
166 +v0.2 : 2018/05/01 发布此规范
...\ No newline at end of file ...\ No newline at end of file