发布于 

开发规范

前端

项目命名全部采用kebab-case命名，字母小写，以短横分隔单词，示例：my-project-name
目录命名全部采用kebab-case命名，字母小写，以短横分隔单词，有复数结构时，要采用复数命名法，缩写不用复数，示例：scripts / styles / components / images / assets / views / utils / custom-themes / layout / img / doc / api / router
文件命名全部采用kebab-case命名，字母小写，以短横分隔单词，示例：render-dom.js / home.css / home-banner.png

  • 扩展名: 用 .tsx 作为组件扩展名。
  • 文件名: 用大驼峰作为文件名，如：ReservationCard.tsx。
  • 参数命名: React 组件用大驼峰，组件的实例用小驼峰。 eslint: react/jsx-pascal-case
    组件命名: 文件名作为组件名。例如：ReservationCard.jsx 应该用 ReservationCard 作为参数名。 然而，对于一个文件夹里的跟组件，应该用 index.jsx 作为文件名，同时用文件夹名作为组件名
    高阶组件HOC命名: 用高阶组件名和传入的组件名组合作为生成的组件的 displayName。 举个例子，一个高阶组件 withFoo()， 当传入一个组件 Bar 应该生成一个新的组件，他的 displayName 属性是 withFoo(Bar)。

命名严禁拼音和英文混合方式，更不允许直接使用中文，使用有意义且规范的缩写，避免望文不知义
除了使用语义化标签，一个网页还需要遵守一定的结构和顺序，自上而下，从左到右，保持一定的顺序

1
2
3
4
5
6
7
8
9
10
11
<div class="app-container"> 
    <!-- header --> 
    <div class="header-container"></div> 
    <!-- main --> 
    <div class="main-container"> 
        <div class="left-box"></div> 
        <div class="content-box"></div> 
     </div> 
     <!-- footer --> 
     <div class="footer-container"></div> 
 </div>

后端

Java，项目包名：com.touchsmail
sql名称:touchsmail

命名

数据库表名规范:模块名称_表名，比如第三方模块的ai配置表名字:third_party_ai_config
项目命名全部采用小写方式， 以中划线分隔，例如：third-party
表名对应包下的包的命名规范
controller：Controller集合
facade：调用Service的逻辑集合，要包含接口和实现类，实现类用@Component注入
service：MyBatis-Plus的Service，里边不要写任何代码，只用于被facade调用。
mapper：MyBatis-Plus的Mapper，被service调用。如果要写SQL，facade直接去调即可。
entity：MyBatis-Plus的DAO（数据库对象）。
bo：入参实体类
vo：返回值实体类
dto:传输
constant：常量。比如：枚举类、Interface常量类
helper：业务工具，比如：组装实体类的字段
schedule：定时任务，比如：xxl-job的定时任务
mq：mq消费者
strategy：策略模式（假如用到策略模式的话）。其他设计模式也一样，单独写一个包，以设计模式的名字命名。
common 目录需要依照项目进行特定的修改，示例

1
2
3
4
5
6
7
8
9
src 
|-- common 
|-- |--- anno          通用注解，比如权限，登录等等
|-- |--- constant      通用常量，比如 ResponseCodeConst
|-- |--- domain        全局的 javabean，比如 BaseEntity,PageParamDTO 等
|-- |--- exception     全局异常，如 BusinessException
|-- |--- json          json 类库，如 LongJsonDeserializer，LongJsonSerializer
|-- |--- swagger       swagger 文档
|-- |--- validator     适合各个项目的通用 validator，如 CheckEnum，CheckBigDecimal 等

config 目录依照项目进行特定的修改，示例

1
2
3
4
5
6
src                               
|-- config                            项目的所有配置信息
|-- |--- MvcConfig                    mvc的相关配置，如interceptor,filter等
|-- |--- DataSourceConfig             数据库连接池的配置
|-- |--- MybatisConfig                mybatis的配置
|-- |--- ....                         其他

dao层方法命名规范
获取单个对象的方法用 get 做前缀。
获取多个对象的方法用 list 做前缀。
获取统计值的方法用 count 做前缀。
插入的方法用 save/insert 做前缀。
删除的方法用 remove/delete 做前缀。
修改的方法用 update 做前缀。

注释

TODO描述已知待改进、待补充的修改点
FIXME 用来描述已知缺陷
函数注释参考：

1
2
3
4
5
6
/**
xxx方法
用来干啥的
@param 参数1，是啥
@return 参数2，是啥
*/

其他

数据库里,时间日期统一存储时间戳，全局用1个静态工具函数来转为具体日期时间
无论是 controller，service，manager，dao 亦或是其他的代码，每个方法最多 3 个参数，如果超出 3 个参数的话，要封装成 javabean 对象
要用枚举来表示类型，不要用数字。比如：有三种支付方式：微信、支付宝、银行卡，则这样定义枚举：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package com.example.pay;
 
public enum PayType {
    ALIPAY("支付宝支付"),
    WECHAT_PAY("微信支付"),
    BANK_CARD_PAY("银行卡支付")
    ;

    /**
     * 描述
     */
    private final String description;

    PayType(String description) {
        this.description = description;
    }

    public String getDescription() {
        return description;
    }
}

controller只充当路由的角色，只允许使用@Valid 注解做简单的校验，不做任何的业务逻辑操作，不做任何的参数、业务校验，不做任何的数据组合、拼装、赋值等操作
只能在 controller 层获取当前请求用户，并传递给 service 层
接口路径驼峰命名
接口路径前面统一带/

公共

代码推送：
feat: 新功能
fix: 修补bug
docs: 文档
style: 格式
refactor: 重构
chore: 构建过程或辅助工具的变动
revert: 撤销，版本回退
perf: 性能优化
test：测试
improvement: 改进
例如：新增用户登陆 feat:UserLogin
不确定的功能测试开发，自己新建1个分支，开发测试没问题后再合并回去，然后删除测试用的分支
提交前应该先编译一次，防止出现编译都报错的情况
提交前检查代码是否格式化，是否符合代码规范，无用的包引入、变量是否清除等
配置文件按环境区分，使用环境变量来切换
线上环境尽量打错误级别的日志

分享文章
快来参与讨论吧