开发规范 · 《灯灯》中后台快速开发平台开发手册

使用本框架作为开发项目,必须遵守以下规范. # 开发工具强制统一 - 前端: VS Code - 后端: IntelliJ IDEA - 数据库设计: CHINER - 数据库客户端: DBeaver # IDEA 强制安装插件 - Lombok：自动生成get set等方法 # IDEA 推荐安装插件 - Maven Helper： maven 依赖排查 - Free Mybatis plugin: mybatis xml 快速切换 - RestfulTool：接口查找 - Alibaba Java Coding Guidelines ：阿里代码编码指南 - Git commit Template： git 提交消息模板 - GitToolBox： Git工具 # VS Code 推荐安装插件 * [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify)\- Iconify 图标插件 * [windicss IntelliSense](https://marketplace.visualstudio.com/items?itemName=voorjaar.windicss-intellisense)\- windicss 提示插件 * [I18n-ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally)\- i18n 插件 * [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur)\- vue 开发必备（也可以选择 Volar） * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)\- 脚本代码检查 * [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)\- 代码格式化 * [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)\- css 格式化 * [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv)\- .env 文件高亮 # 约定 - 源码、jdk、mysql、redis、rabbitmq、nacos、seata等存放路径禁止包含中文、空格、特殊字符等。 ``` 正例: D:/projects/lamp-cloud D:/projects/lamp-boot D:/projects/lamp-util D:/projects/tools/nacos_121 D:/projects/tools/redis D:/projects/tools/seata 反例： D:/Program Files/lamp-cloud D:/Program Files/lamp-boot D:/Program Files/lamp-util D:/Program Files/视频配套项目软件_window版（配置文件被群主优化过）/nacos_121 D:/Program Files/视频配套项目软件_window版（配置文件被群主优化过）/redis D:/Program Files/视频配套项目软件_window版（配置文件被群主优化过）/seata ``` # 数据库设计 (参考c_user表) * 使用CHINER来设计表结构 * 必须显式指定`主键`, 勿用复合主键. 主键的命名统一为: `id` * 任何表至少包含3个字段： bigint id、 datetime create_time、bigint created_by (可以自行修改 EntityType) * 关于状态字段根据业务含义命名为: state、status - 如（隐藏、显示），（是、否），（可用、不可用）、(启用、禁用) 等字段用 state - 如 OrderedStatus, ShippingStatus,ReceiptedStatus 等字段用 status * 界面上要显示成树形结构的表, 至少需要4个字段: id、parent_id、label、sort_value * 表中有以下含义的字段, 尽可能的采用同样的命名规则: - 名称: name (树型结构用: label) - 编码: code - 描述: describe_ - 最后修改数据的用户ID: updated_by - 最后修改数据的时间: update_time - 是否内置数据: readonly_ * POJO 类的布尔属性不能加 is，而数据库字段必须加 is_，要求在 resultMap 中进行字段与属性之间的映射。 * 主键索引名为 pk_字段名；唯一索引名为 uk_字段名；普通索引名则为 idx_字段名。说明：pk_ 即 primary key；uk_ 即 unique key；idx_ 即 index 的简称 * 不得使用外键与级联，一切外键概念必须在应用层解决 * 不用存储过程 * 数据库名、表名、字段名统一使用小写 + `_` * varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。 * 表名命名规则: “b_业务名称_表的作用” 、 “c_业务名称_表的作用” . `b_ ` 表示业务表, `c_`表示核心表(权限系统的一整套) * 表、字段必须加注释 * 表名注释支持换行，第一行会被视为表名。表的介绍请换行填写。 * 字段的第一行视为字段简介，详细介绍和枚举类型请换行 * 所有字段尽量根据业务设置合理的`缺省值`，尽量避免表中出现 NULL值 * 当字段为外键时，字段名为：关联表\_id，注释需要在字段注释基础上，换行加上`#关联表表名`来说明关联的哪张表。（注意英文#号） * 当字段为枚举时，需按照下面当格式添加注释： ~~~ 注释模板1：注释内容 #枚举类名{枚举值英文名:"枚举值英文注释"; ...} 注释模板2：注释内容 #枚举类名{枚举值英文名:val,"枚举值英文注释"; ...} 注释模板3：注释内容 #枚举类名{枚举值英文名:val,"枚举值英文注释",val2; ...} 注释模板4：注释内容 #{枚举值英文名:"枚举值英文注释"; ...} 其中枚举类名可以没有，如果没有，则生成的枚举值名为：表对应的实体名 + 当前字段对应的属性名(首字母大写) + Enum 枚举值例子：文件类型 #FileType{PAN:云盘数据;API:接口数据} 数据类型 #DataType{DIR:1,目录;IMAGE:2,图片;VIDEO:3,视频;AUDIO:4,音频;DOC:5,文档;OTHER:6,其他} 数据类型 #{DIR:目录;IMAGE:图片;VIDEO:视频;AUDIO:音频;DOC:文档;OTHER:其他} ~~~ * 当字段需要使用Echo模块回显功能时, 需要按照下面当格式添加注释 ~~~ 模版1: @Echo(api = ORG_ID_CLASS, beanClass = Org.class) 模版2: @Echo(api = DICTIONARY_ITEM_CLASS, dictType = DictionaryType.NATION) 模版3: @Echo(api = STATION_ID_CLASS) ~~~ * 其他更多约束尽量遵守阿里规范 # 后端 * 详细的代码注释: 类、字段、方法、参数上必须加上doc注释, 方法内部适当的位置加上行注释和块注释. doc注释标明作者(@author)、创建时间(@date)等. * 使用Mybatis-plus 相关查询接口时, 使用系统封装的 Wraps , 而非mp官方的 Wrappers * 在xml写sql 需要使用模糊查询时, 使用自定义类型处理器: `fullLike` , 会自动给你拼接% 如: name like #{name, typeHandler=fullLike} * 尽量多的使用jdk8 + 新特性 * 必须显示的使用泛型 * 暴露给前端的接口参数不宜过多, 使用DTO将必要的字段暴露给前端.避免前端大海捞针! 如: 保存接口, id、createTime、createUser、status 等字段不应该显示在swagger文档的入参里面, 而是由后台自动赋值. * 暴露给前端的接口,一定要在swagger文档上体现合理的注释! * 其他更多约束尽量遵守阿里规范 * 常量的复用层次有五层：跨服务共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。 1）跨服务共享常量：放置在lamp-commom模块中，constant 目录下。 2）应服务共享常量：放置在lamp-xxx-entity中， constant 目录下。 3）子模块共享常量：即在当前模块的 constant 目录下。 4）包内共享常量：即在当前包下单独的 constant 目录下。 5）类内共享常量：直接在类内部 private static final 定义。 * 集合初始化时，指定集合初始值大小。说明：HashMap 使用 HashMap(int initialCapacity) 初始化，如果暂时无法确定集合大小，那么指定默认值（16）即可。正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即 loader factor）默认为 0.75，如果暂时无法确定初始值大小，请设置为 16（即默认值）。 # 前端 * 业务代码都写在`src/views/lamp`下面, 建包规则跟项目的菜单层级保持一致. 包名跟菜单的路由uri保持一致(大小写也要一致) 如: 用户管理的路由为: `#/user/user` , 代码就放在`src/views/lamp/user/user/Index.vue` * 其他更多约束尽量遵守阿里规范 # 提交代码规范 1. 每次提交尽量按功能点或bug提交代码，哪怕是只修改了一行代码，一个字母,尽量不要一次性提交过多的功能和bug等 2. 及时拉取、及时提交、及时推送、及时合并； 3. 提交代码前,记得勾选IDEA提交框中的`Reformat code`、`Rearrage code`、`Optimize imports`选项 3. 提交代码时按照以下模版进行注释 type: 用于说明 commit的类别，只允许使用下面几个标识: fix：修补bug hotfix：紧急修复bug chore：构建过程或辅助工具的变动 docs：文档（documentation） feat：新功能（feature） refactor：重构（即不是新增功能，也不是修改bug的代码变动） style：仅仅修改了空格、缩进等，不改变代码逻辑（不影响代码运行的变动） test：增加测试 revert：回滚到上一个版本； perf：改善性能和体现的修改 build：改变构建流程，新增依赖库、工具等（例如webpack修改）； - scope of this change : 本次变更范围用于描述改动的范围，格式为项目名/模块名，例如： node-pc/common rrd-h5/activity，而we-sdk不需指定模块名。如果一次commit修改多个模块，建议拆分成多次commit，以便更好追踪和维护。 - short description : 简要说明 - Long description : 详细说明 - breaking changes : 不兼容变动 break changes指明是否产生了破坏性修改，涉及break changes的改动必须指明该项，类似版本升级、接口参数减少、接口删除、迁移等。 - close issue : 关闭指定Issue