# ds-platform

**Repository Path**: wu.123/ds-platform

## Basic Information

- **Project Name**: ds-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-10-27
- **Last Updated**: 2021-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

##1. 项目结构

```powershell
├─controller   (控制器模块)
├─dao          (对象关系映射模块，仅mybatis-plus框架)
├─entity       (实体模块)
├─service      (业务API定义模块)
│  └─curd      (业务CRUD-SQL实现模块)
│  └─impl      (业务API实现模块)
├─vo           (默认空文件夹)
│  └─req       (业务请求参数模块)
│  └─resp      (业务响应参数模块)
└─xml          (复杂原生SQL模块，仅mybatis-plus框架)
```

## 2.接口定义规则

```powershell
创建表记录：	POST /{控制器路由名称}/create
修改表记录：	POST /{控制器路由名称}/update/{id}
删除指定表记录：  POST /{控制器路由名称}/delete/{id}
分页查询表记录：  GET /{控制器路由名称}/list
获取指定记录详情： GET /{控制器路由名称}/{id}
```
******************************************************
大数据
1.3.1 表命名
ODS层命名为ods_表名 。
DIM层命名为dim_表名。
DWD层命名为dwd_表名。
DWS层命名为dws_表名 。
DWT层命名为dwt_表名。
ADS层命名为ads_表名。
临时表命名为tmp_表名。


## (八) 注释规约

1. 【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用// xxx方式。
   <br><span style="color:orange">说明</span>：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
2. 【强制】所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
   <br><span style="color:orange">说明</span>：对子类的实现要求，或者调用注意事项，请一并说明。
3. 【强制】所有的类都必须添加创建者和创建日期。
4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用`//`注释。方法内部多行注释使用`/* */`注释，注意与代码对齐。
5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
6. 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
   <br><span style="color:red">反例</span>：“TCP连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
7. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
   <br><span style="color:orange">说明</span>：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
8. 【参考】谨慎注释掉代码。在上方详细说明<，而不是简单地注释掉。如果无用，则删除。
   <br><span style="color:orange">说明</span>：代码被注释掉有两种可能性：
   1）后续会恢复此段代码逻辑。
   2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。
9. 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同
   天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
10. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
    <br><span style="color:red">反例</span>：
 ```
 // put elephant into fridge  
 put(elephant, fridge);      
 方法名put，加上两个有意义的变量名elephant和fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。 
 ```
11. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。  
    1） 待办事宜（**TODO**）:（ 标记人，标记时间，[预计处理时间]）    表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个Javadoc标签）。  
    2） 错误，不能工作（**FIXME**）:（标记人，标记时间，[预计处理时间]）    在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。


*******************************************************


## （三）代码格式
1. 【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成`{}`即可，不需要换行；如果是非空代码块则：
   <br>1） 左大括号前不换行。
   <br>2） 左大括号后换行。
   <br>3） 右大括号前换行。
   <br>4） 右大括号后还有else等代码则不换行；表示终止的右大括号后必须换行。
2. 【强制】 左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。详见第5条下方正例提示。
   <br><span style="color:red">反例</span>：
```
if (空格a == b空格)
```
3. 【强制】if/for/while/switch/do等保留字与括号之间都必须加空格。
4. 【强制】任何二目、三目运算符的左右两边都需要加一个空格。
   <br><span style="color:orange">说明</span>：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。
5. 【强制】采用4个空格缩进，禁止使用tab字符。
   <br><span style="color:orange">说明</span>：
   如果使用tab缩进，必须设置1个tab为4个空格。IDEA设置tab为4个空格时，请勿勾选`Use tab character`；而在eclipse中，必须勾选`insert spaces for tabs`。
   <br><span style="color:green">正例</span>： （涉及1-5点）

          public static void main(String[] args) {
              // 缩进4个空格
              String say = "hello";
              // 运算符的左右必须有一个空格
              int flag = 0;
              // 关键词if与括号之间必须有一个空格，括号内的f与左括号，0与右括号不需要空格
              if (flag == 0) {
                  System.out.println(say);
              }
              // 左大括号前加空格且不换行；左大括号后换行
              if (flag == 1) {
                  System.out.println("world");
                  // 右大括号前换行，右大括号后有else，不用换行
              } else {
                  System.out.println("ok");
                  // 在右大括号后直接结束，则必须换行
              }
          }

6. 【强制】注释的双斜线与注释内容之间有且仅有一个空格。
   <br><span style="color:green">正例</span>：
```
// 这是示例注释，请注意在双斜线之后有一个空格  
String ygb = new String(); 
```
7. 【强制】单行字符数限制不超过120个，超出需要换行，换行时遵循如下原则：
   <br>1）第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。
   <br>2）运算符与下文一起换行。
   <br>3）方法调用的点符号与下文一起换行。
   <br>4） 方法调用时，多个参数，需要换行时，在逗号后进行。
   <br>5） 在括号前不要换行，见反例。
   <br><span style="color:green">正例</span>：
```
StringBuffer sb = new StringBuffer();
     // 超过120个字符的情况下，换行缩进4个空格，点号和方法名称一起换行
    sb.append("zi").append("xin")...
                   .append("huang")...
                   .append("huang")...
                   .append("huang");
```
<br><span style="color:red">反例</span>：
```
StringBuffer sb = new StringBuffer();  
// 超过120个字符的情况下，不要在括号前换行  
sb.append("zi").append("xin")...append      
("huang");    
// 参数很多的方法调用可能超过120个字符，不要在逗号前换行  
method(args1, args2, args3, ... 
, argsX); 
```
8. 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。
   <br><span style="color:green">正例</span>：下例中实参的"a",后边必须要有一个空格。
```
method("a", "b", "c"); 
```
9. 【强制】IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式，不要使用Windows格式。
10. 【推荐】没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。
    <br><span style="color:green">正例</span>：
```
int a = 3;  
long b = 4L;  
float c = 5F;  
StringBuffer sb = new StringBuffer();
```
<span style="color:orange">说明</span>：增加sb这个变量，如果需要对齐，则给a、b、c都要增加几个空格，在变量比较多的情况下，是非常累赘的事情。
11. 【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。
    <br><span style="color:orange">说明</span>：没有必要插入**多个空行**进行隔开。
******************************************************

# 一、编程规约
##（一）命名风格

1. 【强制】代码中的命名均不能以<strong>下划线或美元符号</strong>开始，也不能以<strong>下划线或美元符号</strong>结束。
   <br><span style="color:red">反例</span>：`_name / __name / $name / name_ / name$ / name__`
2. 【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
   <br><span style="color:orange">说明</span>：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。
   <br><span style="color:green">正例</span>：alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。
   <br><span style="color:red">反例</span>：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3
3. 【强制】类名使用`UpperCamelCase`风格，但以下情形例外：DO / BO / DTO / VO / AO / PO等。
   <br><span style="color:green">正例</span>：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
   <br><span style="color:red">反例</span>：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
4. 【强制】方法名、参数名、成员变量、局部变量都统一使用`lowerCamelCase`风格，必须遵从驼峰形式。
   <br><span style="color:green">正例</span>： localValue / getHttpMessage() / inputUserId
5. 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
   <br><span style="color:green">正例</span>：MAX_STOCK_COUNT
   <br><span style="color:red">反例</span>：MAX_COUNT
6. 【强制】抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类名开始，以Test结尾。
7. 【强制】类型与中括号紧挨相连来定义数组。
   <br><span style="color:green">正例</span>：定义整形数组<code>int[] arrayDemo;</code>
   <br><span style="color:red">反例</span>：在main参数中，使用<code>String args[]</code>来定义。
8. 【强制】POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。
   <br><span style="color:red">反例</span>：定义为基本数据类型<code>Boolean isDeleted；</code>的属性，它的方法也是<code>isDeleted()</code>，RPC框架在反向解析的时候，“误以为”对应的属性名称是deleted，导致属性获取不到，进而抛出异常。
9. 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
   <br><span style="color:green">正例</span>：应用工具类包名为com.alibaba.ai.util、类名为MessageUtils（此规则参考spring的框架结构）
10. 【强制】杜绝完全不规范的缩写，避免望文不知义。
    <br><span style="color:red">反例</span>：AbstractClass“缩写”命名成AbsClass；condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。
11. 【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
    <br><span style="color:green">正例</span>：从远程仓库拉取代码的类命名为PullCodeFromRemoteRepository。
    <br><span style="color:red">反例</span>：变量int a; 的随意命名方式。
12. 【推荐】如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。
    <br><span style="color:orange">说明</span>：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
    <br><span style="color:green">正例</span>：
```
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver; 
```
13. 【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
    <br><span style="color:green">正例</span>：接口方法签名void f(); 接口基础常量String COMPANY = "alibaba";
    <br><span style="color:red">反例</span>：接口方法定义public abstract void f();
    <br><span style="color:orange">说明</span>：JDK8中接口允许有默认实现，那么这个default方法，是对所有实现类都有价值的默认实现。
14. 接口和实现类的命名有两套规则：  
    1）【强制】对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。
    <br><span style="color:green">正例</span>：CacheServiceImpl实现CacheService接口。<br>
    2） 【推荐】 如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able的形式）。
    <br><span style="color:green">正例</span>：AbstractTranslator实现 Translatable。
15. 【参考】枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
    <br><span style="color:orange">说明</span>：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
    <br><span style="color:green">正例</span>：枚举名字为ProcessStatusEnum的成员名称：SUCCESS / UNKNOWN_REASON。
16. 【参考】各层命名规约：  
    A) Service/DAO层方法命名规约<br>
    1） 获取单个对象的方法用get作前缀。
    <br>2） 获取多个对象的方法用list作前缀。
    <br>3） 获取统计值的方法用count作前缀。    
    4） 插入的方法用save/insert作前缀。    
    5） 删除的方法用remove/delete作前缀。    
    6） 修改的方法用update作前缀。
    <br>B) 领域模型命名规约 <br>
    1） 数据对象：xxxDO，xxx即为数据表名。    
    2） 数据传输对象：xxxDTO，xxx为业务领域相关的名称。    
    3） 展示对象：xxxVO，xxx一般为网页名称。    
    4） POJO是DO/DTO/BO/VO的统称，禁止命名成xxxPOJO。
******************************************************
# 数据库规范
## (一) 建表规约
1. 【强制】表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsigned tinyint（ 1表示是，0表示否）。
   <br><span style="color:orange">说明</span>：任何字段如果为非负数，必须是`unsigned`。
   <br><span style="color:green">正例</span>：表达逻辑删除的字段名`is_deleted`，1表示删除，0表示未删除。
2. 【强制】表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。 <br><span style="color:orange">说明</span>：MySQL在Windows下不区分大小写，但在Linux下默认是区分大小写。因此，数据库名、表名、字段名，都不允许出现任何大写字母，避免节外生枝。 <br><span style="color:green">正例</span>：aliyun_admin，rdc_config，level3_name <br><span style="color:red">反例</span>：AliyunAdmin，rdcConfig，level_3_name
3. 【强制】表名不使用复数名词。
   <br><span style="color:orange">说明</span>：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于DO类名也是单数形式，符合表达习惯。
4. 【强制】禁用保留字，如`desc`、`range`、`match`、`delayed`等，请参考MySQL官方保留字。
5. 【强制】主键索引名为pk_字段名；唯一索引名为uk_字段名；普通索引名则为idx_字段名。
   <br><span style="color:orange">说明</span>：pk_ 即primary key；uk_ 即 unique key；idx_ 即index的简称。
6. 【强制】小数类型为decimal，禁止使用float和double。
   <br><span style="color:orange">说明</span>：float和double在存储的时候，存在精度损失的问题，很可能在值的比较时，得到不正确的结果。如果存储的数据范围超过decimal的范围，建议将数据拆成整数和小数分开存储。
7. 【强制】如果存储的字符串长度几乎相等，使用char定长字符串类型。
8. 【强制】varchar是可变长字符串，不预先分配存储空间，长度不要超过5000，如果存储长度大于此值，定义字段类型为text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
9. 【强制】表必备三字段：id, gmt_create, gmt_modified。
   <br><span style="color:orange">说明</span>：其中id必为主键，类型为unsigned bigint、单表时自增、步长为1。gmt_create, gmt_modified的类型均为datetime类型，前者现在时表示主动创建，后者过去分词表示被动更新。
10. 【推荐】表的命名最好是加上“业务名称_表的作用”。
    <br><span style="color:green">正例</span>：alipay_task / force_project / trade_config
11. 【推荐】库名与应用名称尽量一致。
12. 【推荐】如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。
13. 【推荐】字段允许适当冗余，以提高查询性能，但必须考虑数据一致。冗余字段应遵循：  
    1）不是频繁修改的字段。  
    2）不是varchar超长字段，更不能是text字段。
    <br><span style="color:green">正例</span>：商品类目名称使用频率高，字段长度短，名称基本一成不变，可在相关联的表中冗余存储类目名称，避免关联查询。
14. 【推荐】单表行数超过500万行或者单表容量超过2GB，才推荐进行分库分表。 <br><span style="color:orange">说明</span>：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。
15. 【参考】合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提升检索速度。 <br><span style="color:green">正例</span>：如下表，其中无符号值可以避免误存负数，且扩大了表示范围。

| 对象  | 年龄区间 | 类型  | 字节  |
| ------------- |:-------------| :----- |:----- |
| 人 |150岁之内  | unsigned tinyint|1|
| 龟 |数百岁 | unsigned smallint |2|
| 恐龙化石 |数千万岁 | unsigned int |4|
| 太阳 |约50亿年 | unsigned bigint |8|