Skip to content

Commit a0a054d

Browse files
umasuoumasuo
umasuo
authored and
umasuo
committed
add docs
1 parent 0eb48f0 commit a0a054d

12 files changed

+762
-0
lines changed

‎LICENSE

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
Apache License
2+
Version 2.0, January 2004
3+
http://www.apache.org/licenses/
4+
5+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6+
7+
1. Definitions.
8+
9+
"License" shall mean the terms and conditions for use, reproduction, and
10+
distribution as defined by Sections 1 through 9 of this document.
11+
12+
"Licensor" shall mean the copyright owner or entity authorized by the copyright
13+
owner that is granting the License.
14+
15+
"Legal Entity" shall mean the union of the acting entity and all other entities
16+
that control, are controlled by, or are under common control with that entity.
17+
For the purposes of this definition, "control" means (i) the power, direct or
18+
indirect, to cause the direction or management of such entity, whether by
19+
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
20+
outstanding shares, or (iii) beneficial ownership of such entity.
21+
22+
"You" (or "Your") shall mean an individual or Legal Entity exercising
23+
permissions granted by this License.
24+
25+
"Source" form shall mean the preferred form for making modifications, including
26+
but not limited to software source code, documentation source, and configuration
27+
files.
28+
29+
"Object" form shall mean any form resulting from mechanical transformation or
30+
translation of a Source form, including but not limited to compiled object code,
31+
generated documentation, and conversions to other media types.
32+
33+
"Work" shall mean the work of authorship, whether in Source or Object form, made
34+
available under the License, as indicated by a copyright notice that is included
35+
in or attached to the work (an example is provided in the Appendix below).
36+
37+
"Derivative Works" shall mean any work, whether in Source or Object form, that
38+
is based on (or derived from) the Work and for which the editorial revisions,
39+
annotations, elaborations, or other modifications represent, as a whole, an
40+
original work of authorship. For the purposes of this License, Derivative Works
41+
shall not include works that remain separable from, or merely link (or bind by
42+
name) to the interfaces of, the Work and Derivative Works thereof.
43+
44+
"Contribution" shall mean any work of authorship, including the original version
45+
of the Work and any modifications or additions to that Work or Derivative Works
46+
thereof, that is intentionally submitted to Licensor for inclusion in the Work
47+
by the copyright owner or by an individual or Legal Entity authorized to submit
48+
on behalf of the copyright owner. For the purposes of this definition,
49+
"submitted" means any form of electronic, verbal, or written communication sent
50+
to the Licensor or its representatives, including but not limited to
51+
communication on electronic mailing lists, source code control systems, and
52+
issue tracking systems that are managed by, or on behalf of, the Licensor for
53+
the purpose of discussing and improving the Work, but excluding communication
54+
that is conspicuously marked or otherwise designated in writing by the copyright
55+
owner as "Not a Contribution."
56+
57+
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
58+
of whom a Contribution has been received by Licensor and subsequently
59+
incorporated within the Work.
60+
61+
2. Grant of Copyright License.
62+
63+
Subject to the terms and conditions of this License, each Contributor hereby
64+
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
65+
irrevocable copyright license to reproduce, prepare Derivative Works of,
66+
publicly display, publicly perform, sublicense, and distribute the Work and such
67+
Derivative Works in Source or Object form.
68+
69+
3. Grant of Patent License.
70+
71+
Subject to the terms and conditions of this License, each Contributor hereby
72+
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
73+
irrevocable (except as stated in this section) patent license to make, have
74+
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
75+
such license applies only to those patent claims licensable by such Contributor
76+
that are necessarily infringed by their Contribution(s) alone or by combination
77+
of their Contribution(s) with the Work to which such Contribution(s) was
78+
submitted. If You institute patent litigation against any entity (including a
79+
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
80+
Contribution incorporated within the Work constitutes direct or contributory
81+
patent infringement, then any patent licenses granted to You under this License
82+
for that Work shall terminate as of the date such litigation is filed.
83+
84+
4. Redistribution.
85+
86+
You may reproduce and distribute copies of the Work or Derivative Works thereof
87+
in any medium, with or without modifications, and in Source or Object form,
88+
provided that You meet the following conditions:
89+
90+
You must give any other recipients of the Work or Derivative Works a copy of
91+
this License; and
92+
You must cause any modified files to carry prominent notices stating that You
93+
changed the files; and
94+
You must retain, in the Source form of any Derivative Works that You distribute,
95+
all copyright, patent, trademark, and attribution notices from the Source form
96+
of the Work, excluding those notices that do not pertain to any part of the
97+
Derivative Works; and
98+
If the Work includes a "NOTICE" text file as part of its distribution, then any
99+
Derivative Works that You distribute must include a readable copy of the
100+
attribution notices contained within such NOTICE file, excluding those notices
101+
that do not pertain to any part of the Derivative Works, in at least one of the
102+
following places: within a NOTICE text file distributed as part of the
103+
Derivative Works; within the Source form or documentation, if provided along
104+
with the Derivative Works; or, within a display generated by the Derivative
105+
Works, if and wherever such third-party notices normally appear. The contents of
106+
the NOTICE file are for informational purposes only and do not modify the
107+
License. You may add Your own attribution notices within Derivative Works that
108+
You distribute, alongside or as an addendum to the NOTICE text from the Work,
109+
provided that such additional attribution notices cannot be construed as
110+
modifying the License.
111+
You may add Your own copyright statement to Your modifications and may provide
112+
additional or different license terms and conditions for use, reproduction, or
113+
distribution of Your modifications, or for any such Derivative Works as a whole,
114+
provided Your use, reproduction, and distribution of the Work otherwise complies
115+
with the conditions stated in this License.
116+
117+
5. Submission of Contributions.
118+
119+
Unless You explicitly state otherwise, any Contribution intentionally submitted
120+
for inclusion in the Work by You to the Licensor shall be under the terms and
121+
conditions of this License, without any additional terms or conditions.
122+
Notwithstanding the above, nothing herein shall supersede or modify the terms of
123+
any separate license agreement you may have executed with Licensor regarding
124+
such Contributions.
125+
126+
6. Trademarks.
127+
128+
This License does not grant permission to use the trade names, trademarks,
129+
service marks, or product names of the Licensor, except as required for
130+
reasonable and customary use in describing the origin of the Work and
131+
reproducing the content of the NOTICE file.
132+
133+
7. Disclaimer of Warranty.
134+
135+
Unless required by applicable law or agreed to in writing, Licensor provides the
136+
Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
137+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
138+
including, without limitation, any warranties or conditions of TITLE,
139+
NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
140+
solely responsible for determining the appropriateness of using or
141+
redistributing the Work and assume any risks associated with Your exercise of
142+
permissions under this License.
143+
144+
8. Limitation of Liability.
145+
146+
In no event and under no legal theory, whether in tort (including negligence),
147+
contract, or otherwise, unless required by applicable law (such as deliberate
148+
and grossly negligent acts) or agreed to in writing, shall any Contributor be
149+
liable to You for damages, including any direct, indirect, special, incidental,
150+
or consequential damages of any character arising as a result of this License or
151+
out of the use or inability to use the Work (including but not limited to
152+
damages for loss of goodwill, work stoppage, computer failure or malfunction, or
153+
any and all other commercial damages or losses), even if such Contributor has
154+
been advised of the possibility of such damages.
155+
156+
9. Accepting Warranty or Additional Liability.
157+
158+
While redistributing the Work or Derivative Works thereof, You may choose to
159+
offer, and charge a fee for, acceptance of support, warranty, indemnity, or
160+
other liability obligations and/or rights consistent with this License. However,
161+
in accepting such obligations, You may act only on Your own behalf and on Your
162+
sole responsibility, not on behalf of any other Contributor, and only if You
163+
agree to indemnify, defend, and hold each Contributor harmless for any liability
164+
incurred by, or claims asserted against, such Contributor by reason of your
165+
accepting any such warranty or additional liability.
166+
167+
END OF TERMS AND CONDITIONS
168+
169+
APPENDIX: How to apply the Apache License to your work
170+
171+
To apply the Apache License to your work, attach the following boilerplate
172+
notice, with the fields enclosed by brackets "{}" replaced with your own
173+
identifying information. (Don't include the brackets!) The text should be
174+
enclosed in the appropriate comment syntax for the file format. We also
175+
recommend that a file or class name and description of purpose be included on
176+
the same "printed page" as the copyright notice for easier identification within
177+
third-party archives.
178+
179+
Copyright 2018 YING
180+
181+
Licensed under the Apache License, Version 2.0 (the "License");
182+
you may not use this file except in compliance with the License.
183+
You may obtain a copy of the License at
184+
185+
http://www.apache.org/licenses/LICENSE-2.0
186+
187+
Unless required by applicable law or agreed to in writing, software
188+
distributed under the License is distributed on an "AS IS" BASIS,
189+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
190+
See the License for the specific language governing permissions and
191+
limitations under the License.

‎README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# 开发规则与文档
2+
3+
软件有二个根本性原则：正确的业务逻辑与可维护性。
4+
5+
所有的软件开发管理活动都是基于这二个原则来展开：自动测试要求，代码标准，代码审核，文档标准，github 工作流，需求工作流程，设计工作流程，开发环境配置等等。我们明白这些流程、标准、模版不是限制，任何项目都可以定制。最终目的是让整个开发过程自动化和标准化，从而让开发人员把精力放在最关键的创造性工作中。
6+
7+
管理我们的不是这些条条框框和任何经理，是自我高标准驱动与合作精神带来高效产出。
8+
9+
## 文档结构
10+
11+
对全体有用的放在根目录，超过十个之后在建立相关分类目录。
12+
13+
第一层可以有前端，后端，需求，设计。

‎backend/basic-service-developer-flow.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# 后端服务的开发基本流程
2+
定开发后端服务的基本原则是为了能够更规范的开发我们的服务，也能适当减少沟通带来的成本。
3+
# API类型的服务
4+
API类型的服务需要对外提供API，当前主要以REST 风格的API为主，后期可能会有其他类型的API（GRPC），此类型的服务的基本开发流程：
5+
1. 定义API：定义需要对外输出的API，定义完成之后，对外输出swagger文档，同时需要相关人员进行review：主要review：API形式，model
6+
2. 定义存储的数据结构：如果服务需要持久化数据，那么需要在这一步定义清楚需要持久化的数据结构，并明确表明每个字段的含义。主要review点：因我们大部分数据是来源于第三方，所以需要保证数据源的数据被合理的融合进了我们的数据
7+
3. 设计业务逻辑：关键、复杂的业务处理，需要有设计相关文档，可以简单的画出业务执行流程，以及步骤定义。主要review点：逻辑是否可精简（保留核心流程，其他流程走异步之类的）
8+
4. 代码实现：根据设计实现业务逻辑代码。这个部分不需要太多思考，按照设计去实现即可。主要review点：可以设计与实现是否合适
9+
5. 测试用例：这个不要求代码覆盖率以及分支覆盖率，但是要求核心逻辑必须测全
10+
11+
# 独立运行的服务
12+
独立运行的服务，如定时任务、消息处理任务等，次类任务，不需要对外提供API，但是可能需要持久化数据、或者对外发布消息等。与上面的服务类型相比，除了第一步不需要之外，其他的都需要
13+
14+
＃ 代码分支定义与使用
15+
1. 如果服务是一个全新的服务，那么可以再第一版的开发中直接使用master分支
16+
2. 服务一旦上线，需要保证master分支能够随时部署到线上去。也就是需要维持下面几个约定：
17+
1. 每次新版本上线，打个TAG
18+
2. 线上的bugfix，开个bugfix的分支，修复、测试完毕之后，merge到master，并上线
19+
3. 新功能开发，以功能名命名一个分支，并在新分支上进行开发，测试完毕之后合并到master，进行上线
20+
4. 版本会退，如果线上版本出了问题，需要会退，先保留master分支，然后将master分支回退到固定版本
21+

‎backend/java-service-test.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Java微服务测试框架以及方法
2+
当前Java服务采用的是Spock进行测试
3+
具体文档可以参考： http://spockframework.org/

‎backend/service-basic-rule.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# 服务开发的基本规约
2+
- 每个服务，只专注于一个功能模块的开发.
3+
- 在服务之间发送请求的时候，需要带上本地的traceId，并将其置于Header中： “TraceId”

‎frontend/frontend-project-guideline.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# 前端项目指南
2+
3+
## 基本模版
4+
5+
README： 请参考通用的项目 [README.md 模版](../sample-project-readme.md)。
6+
7+
.gitignore: 请参考[.gitignore template](./sample_dot_ignore).

‎frontend/ionic-test.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Ionic Test
2+
3+
Ionic Framework doesn't provide good testing utilities. Currently (2018/05) there are two options: the [Ionic test sample project](https://github.com/ionic-team/ionic-unit-testing-example) and the [clicker seed project](https://github.com/lathonez/clicker). The Ionic test sample is preferred because Ionic 4 is most likely based on it.
4+
5+
## 1. TDD Process
6+
7+
Following the TDD philosophy, the recommended development process is:
8+
9+
- write an e2e test for a specific requirement.
10+
- the e2e test fails
11+
- decide what functionality needs pass the e2e test.
12+
- write a unit test for the functionality.
13+
- the unit test fails.
14+
- implement the code to satisfy the unit test.
15+
- pass the unit test, revise the code if it fails.
16+
- pass the e2e test, add/revise functionality if it fails.
17+
18+
The failure steps of both e2e and unit test are necessary to make sure two things: 1) the test is writting correctly, and 2) force to work within the parameters of the test.
19+
20+
To start a project, first come with a list of requirements and corresponding e2e tests. Then prioritize the requirements and e2e tests to make a minimum viable product (MVP) ASAP.
21+
22+
The key difference between a unit test and an E2E test is that a unit test will test code, whereas an E2E will test behaviour. An e2e test tests the page contents that include the current page and the navigated pages. A unit test only checks the logic of the current page. Therefore starting from the homepage, every e2e test tests the current page content and navigation to child pages. Each page's unit test tests the component logic such as componentent creation and setting member variables from the navigator's parameters.
23+
24+
## 2. Configure for Testing
25+
26+
The ["Testing in Ionic" blog](https://leifwells.github.io/2017/08/27/testing-in-ionic-configure-existing-projects-for-testing/) gives step-by-step configuration instructions. The following is a simplified version.
27+
28+
### Step 1: Install Required NPM Packages
29+
30+
Use the following command to install `karma`, `jasmine`, `protractor` and other utilities.
31+
32+
`npm install --save-dev angular2-template-loader html-loader jasmine jasmine-spec-reporter karma karma-chrome-launcher karma-jasmine karma-jasmine-html-reporter karma-sourcemap-loader karma-webpack karma-coverage-istanbul-reporter istanbul-instrumenter-loader null-loader protractor [email protected] ts-node @types/jasmine @types/node`
33+
34+
Use `ts-loader` 3.x for `webpack` 3.x -- Angular 5 and older uses this version.
35+
36+
### Step 2: Add the Configuration Files
37+
38+
Copy the `test-config` folder (with 5 files) from the [Ionic test sample project](https://github.com/ionic-team/ionic-unit-testing-example) to your project root.
39+
40+
The `karma-config.js` is the Karma configuration file that uses `webpack.test.js`, `karma-test-shim.js`. The `protractor.conf.js` is the Protractor configuration file that specifies the test file path, for example, `'../e2e/**/*.e2e-spec.ts'` means all files with a postfix of `.e2e-spec.ts` in the parent's `e2e` folder.
41+
42+
The `mocks-ionic.js` file is a collection of classes that mock `ionic-angular` classes.
43+
44+
### Step 3: Add Command-line Scripts
45+
46+
Add the following commands to `package.json`:
47+
48+
```json
49+
"test": "karma start ./test-config/karma.conf.js",
50+
"test-ci": "karma start ./test-config/karma.conf.js --single-run",
51+
"test-coverage": "karma start ./test-config/karma.conf.js --coverage",
52+
"e2e": "npm run e2e-update && npm run e2e-test",
53+
"e2e-test": "protractor ./test-config/protractor.conf.js",
54+
"e2e-update": "webdriver-manager update --standalone false --gecko false"
55+
```
56+
57+
### Step 4: Add e2e Testing
58+
59+
Copy the `e2e` folder from the [Ionic test sample project](https://github.com/ionic-team/ionic-unit-testing-example) to your project root.
60+
61+
The `tsconfig.json` is a compiler configuration file. The `app.e2e-spec.ts` is an example test file and the `app.po.ts` is an example page object file that provides test utilities.
62+
63+
### Step 5: Add Your Unit and e2e tests
64+
65+
Unit tests have a postfix of `.spec.ts` and are stored with their corresponding components or class/funtion files. e2e tests have a postfix of `.e2e-spec.ts` and are put in `e2e` folder at the project root.
66+
67+
## 3 Run Tests
68+
69+
Run `ionic serve` before run the e2e test, otherwise Protractor cannot connect to the pages.

0 commit comments

Comments
 (0)