# admin_v0 **Repository Path**: awd1620/admin_v0 ## Basic Information - **Project Name**: admin_v0 - **Description**: 通用系统架构 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-09-23 - **Last Updated**: 2024-07-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## admin项目 ## 脚手架后端工程 ### 简介 开发规范 尽量遵循阿里开发规范 原则: code review 少写代码注释 多写业务注释, 尽量多写注释 核心模块 必须要有：需求评审，架构图，流程图 形成 .md文件 ### 使用说明 ps：新人注意了 仔细看 a）我们的jiraiya-service 采用gradle多模块开发，若添加新模块，请更新最外层setting.gradle中include属性 b) 热部署 https://www.jianshu.com/p/f658fed35786 c) 第一次启动项目的同学请注意！ 在本地 mysql 创建jiraiya数据库 (注意你的数据库编码 否则还得重来) jiraiya-web项目下的 application-dev请将第15行 initialization-mode 属性置为always 这样就会自动给你初始化数据库和数据了 同理每次有同学喊你更新数据库了 都是这样 用完请换回never 我知道这样不合适 放心 以后我会让你舒服的用 d) 新来的同学请注意 我们所有的版本号请不要随意更改 牵扯到配置文件不要乱动 若需要更新请及时通知王春颖及涉及到的各位 e) gradle6.7需要idea2020支持 f) 如gradle构建内存溢出，修改IDEA安装目录下bin包下的idea64.exe.vmoptions内容： -Xms1024m -Xmx2048m -XX:ReservedCodeCacheSize=1024m g) 如果启动里项目出现命令行过长，打开WebApplication配置，设置shorten command line项：JAR manifest; ### 主要工具依赖的版本 linux centos 7 jdk 1.8 mysql 5.7 tomcat 9.0 maven 3.6.3 redis 6.0 elasticsearch 6.8.1 //暂时没添加 [comment]: <> ( clickhouse 20.x) [comment]: <> ( kafka 2.4.1 ) [comment]: <> ( zookeeer 3.5.8) ### 快速上手 Controller 开发强制使用RestController 这样会加上/api/ 公共url 启动命令：gradle bootRun jiraiya-web:WebApplication 主方法启动 （推荐） 数据库配置文件在applicaiton-${env}.yml 打包命令: gradle build -x test -x test 忽略测试 包位置 build/libs/xxxx.war | jar 其余请仔细看使用说明 若发现你没仔细看 恕不予解答 ### 数据库信息： 本地安装数据库请注意编码格式 安装完终端输入:show variables like "%character%"检查编码格式 统一 utf8 mysql: username: root # 利用 dynamic RSA加密 原密码root password: ENC(VZamSTMi224AH6RUtJGXNldiDp/XEL2ozRhBUu/o9ChodT4JEb9kE/j0EFhXKbjsfvLVacUW0AUzetA6OrNJug==) url: jdbc:mysql://jiraiyamysql:3306/jiraiya?useSSL=false&serverTimezone=Asia/Shanghai driverClassName: com.mysql.cj.jdbc.Driver mariaDB(windows): 安装遇到的问题: 1. 安装前杀掉mysql的进程,或者卸载mysql 2. 安装成功后, 项目运行失败 报错: 解决办法是 在 /data/my.ini 配置文件中 添加 [mysqld] innodb_large_prefix=ON innodb_file_format=barracuda innodb_file_per_table=ON 3. 安装成功后, 数据中文乱码 解决办法是 a. 先执行命令看是谁乱码了 mariadb> show variables like "%character%"; +--------------------------+---------------------------------+ | Variable_name | Value | +--------------------------+---------------------------------+ | character_set_client | utf8mb4 | | character_set_connection | utf8mb4 | | character_set_database | utf8 | | character_set_filesystem | binary | | character_set_results | utf8mb4 | | character_set_server | latin1 | | character_set_system | utf8 | | character_sets_dir | D:\MariaDB 10.1\share\charsets\ | +--------------------------+---------------------------------+ 8 rows in set (0.03 sec) b. 发现 character_set_server 不是utf-8 解决办法是在 /data/my.ini 配置文件中, 添加 character-set-server=utf8 以及 default-character-set=utf8 [mysqld] character-set-server=utf8 [client] default-character-set=utf8 ### 模块说明 子模块主名称应与父模块一致 ### 全局接口格式 响应成功: { code: 200 message: "OK" data: {} or [] } 响应失败: { code: HTTP_CODE 404, 500 message: "错误消息" data: { errorCode:30001 } } ### 后端表单验证格式 ### 7.mybatis-plus基本使用 多表联查 join 或者 业务处理多表皆可 ### 8.jwt加解密使用 详情见 admin-framework/src/main/java/com/xiangfu/web/jwt/util/JwtTokenUtil.java 工具类 ### 全局异常捕捉日志 利用aspect切面 + logback + slf4j 详情见jiraiya-service\jiraiya-framework\src\main\java\com\xiangfu\framework\aspect\HandleLogAspect.java 会生成三种日志文件 以及 打印控制台 打印日志请使用 slf4j中logger打印 Controller层 统一不需要打印日志 若需要处理业务异常 请继承 CommonException 并严格遵守HttpCode 及 ErrorCode规范 ### 多配置文件适配 从/resouces/application.yml 定义. 例: active:dev prod为生产机 , dev为开发/测试环境 生成环境配置请在 application-prod.yml里写 开发/测试机配置请在 application-dev.yml里写 我们暂时关心 dev ### sql初始化基本使用 framework的资源文件目录下sql包: data.sql是用于初始化表数据(用于创建初始化数据) schema.sql是用于创建表(用于修改字段类型等) clickhouse_init.sql ck初始化SQL 不要动！ 开启与关闭: application-dev.yml中spring.datasoucre.initialization-mode: # always为始终执行初始化(初始化数据覆盖原数据)，never为不执行初始化。 启动项目需初始化数据库 后面加上 --spring.datasoure.initialization-mode=always ### 9.swagger使用 所有前后端接口强制使用swagger 并遵守相关规范 ``` 9.1 swagger-bootstrap-ui地址： localhost:8080/doc.html 9.2 在controller类使用说明 参考com.xiangfu.web.swagger.controller.SwaggerTestController 9.2.1 在类上添加注解 1.@Api(tags = "类描述") ---必写项 9.2.2 在方法上添加注解 1.@ApiOperation(value = "请求简介", notes = "请求详细描述") 2.@ApiOperation("请求描述")，相当于条目1 ---必写项 3.@ApiImplicitParam(name = "属性名", value = "属性描述", required = 是否必填项) ---必写项 4.@ApiImplicitParams({可以写多个@ApiImplicitParam}) 9.3 在请求和返回参数的对象类使用 参考com.xiangfu.web.swagger.bo.Student 9.3.1 类上添加注解 1.@ApiModel("类描述") 9.3.2 属性上添加注解 1.@ApiModelProperty(value = "属性描述",required = 是否必填项) 9.4 注意事项 1.@ApiIgnore 如需忽略某个请求或者类 请在方法或者类上添加这个注解 2.如果返回值data中是对象，请在统一返回值ResultContent中添加泛型 ``` ### git 使用说明 重要必看！！ 1、上班到工位第一件事记得拉取代吗 git pull 见到 'Already up to date' 或者 '已经是最新的' 证明你成功了 2、每日事毕记得push代码 具体操作： git status 查看状态 git add . 添加到git暂存区 git status 查看状态 git commit到本地仓库 git status 查看状态 git pull再次拉取代码确认最新 若冲突 切记与冲突的同事进行商量merge代码 确认无误后 git status 查看状态 git push 提交到远程仓库 显示 everything are up-to-date 说明成功啦 代码搞错的自觉来领罚 ### 目录说明 admin-web web容器 作用是提供内置tomcat启动以及部分配置项 admin-framework 为框架层 作用是给其他模块提供共有的功能或者工具类等 如日志等 [comment]: <> ( jiraiya-core 为核心代码层) [comment]: <> ( jiraiya-sso 单点登录层) [comment]: <> ( jiraiya-sop 安全运维层) ### FAQ ### 数据库相关约定俗成 1、数据库表内时间字段用DateTime类型 因为时间带时区 2、数据库表名与字段名必须用下划线 不可以使用缩写 3、数据库表与字段名称对应model必须用驼峰 4、clickhouse 严格区分大小写 字段尽量加Nullable ### restful 后端接口规范 1、统一接口以 /soc/api 开头 已经全局处理 2、第二个参数以指定permission名称为准 后端将以当前用户所拥有的角色对应相应权限（sys_perssion:module）为准进行权限判断 格式如 $(/api/module) 3、接口以action为结尾 基于sys_perssion表进行请求动作判断 后端将以当前用户所拥有角色对应操作权限进行拦截判断 其中action包括（query、add、delete、update、export、import） 4、最终格式：/api/${module_name}/.../.../${action} ### 错误码说明 错误码分为网络错误和应用程序错误 其中应用程序错误码分为三大类 1、请求错误 包括请求参数类错误 验证码、表单参数等 2、网络错误 比如请求redis mysql es等网络错误 3、响应错误 程序异常报错或BUG ### 统一相应参数说明 ``` 前提:所有响应类型为:ResultContent 若有返回值请加上响应类型对应泛型,例如:查询全部用户响应类型为:ResultContent> 1.操作成功但是没有返回数据，方法为:ResultContent.success() 2.操作成功且有返回数据，方法为:ResultContent.success(返回数据T) 3.操作失败但是没有详细错误信息,方法为ResultContent.success(httpCode) 4.操作失败但是没有详细错误信息,方法为ResultContent.success(httpCode,errorCode) 5.自定义code无数据响应，方法为:ResultContent.custom(httpCode) 6.自定义code有数据响应，方法为:ResultContent.custom(httpCode,响应数据T) ``` ### 后端验证说明 ``` 前提请使用javax.validation.constraints.*内的注解 使用方式: 一.在相关的请求参数类的属性上添加注解,message中可选择输入错误信息 1.@NotNull 此字段不能为null 2.@NotBlank 此字段不能为空字符串、空白字符串(只用于String) 3.@Email 用于验证邮箱 4.@Max、@Min 限定最大值最小值 5.@Pattern(regexp = 正则表达式,message = 验证失败返回信息) 正则验证 6.正则验证和响应的错误返回信息在com.xiangfu.framework.common.CommonConstant中 7.com.xiangfu.framework.common.annotation下面有很多封装好的注解 8.需要在controller类的请求参数前加注解@Valid，否则不生效 二.在controller的请求参数行使用注解，message中可选择输入错误信息 1.请在对应controller类上使用注解@Validated 注意事项:一和二两种方式不要同时使用 三.单独验证唯一性使用方式 throw new ValidationException(HttpCode.BAD_REQUEST, ValidationUtil.validation( CommonConstant.USERNAME_RULE(验证规则), CommonConstant.USERNAME_ONLY_MESSAGE(错误信息), CommonConstant.USERNAME_ATTRIBUTE(属性名))); ``` ### 日志及异常规范 1、日志均用slf4j进行打印 使用方法private static final Logger log = LoggerFactory.getLogger(Class) 2、自定义业务异常需要继承CommonException 这样会被全局异常捕捉到识别为业务异常做处理 3、除 controller 层外 其他业务需要自己处理异常的 请使用logger打印 4、controller 除了特殊处理的业务异常 其余不需要处理 ### WebSocket 返回格式 请求地址： /api/service/websocket 响应成功: { code: 200 message: "OK" data: { "unreadNotifyCount":0 | 2323 } } 这个值代表当前登录用户 未读消息数量 为0时说明没有 响应失败: { code: HTTP_CODE 500 message: "错误消息" data: { errorCode:不一定 } } ### 修改hosts 文件 文件内容 127.0.0.1 jiraiyaredis 127.0.0.1 jiraiyamysql 127.0.0.1 jiraiyack 127.0.0.1 jiraiyaScriptService 方便运维工作 后端需要修改配置文件 MySQL的ip替换为: jiraiyamysql Redis的ip替换为: jiraiyaredis 开发环境也需要修改hosts文件 Mac环境 命令 sudo vim /etc/hosts 在最后添加 ip 域名 127.0.0.1 jiraiyamysql 127.0.0.1 jiraiyaredis Windows环境 使用 vscode 工具打开 C:\Windows\System32\drivers\etc\hosts文件 在最后添加 ip 域名 127.0.0.1 jiraiyamysql 127.0.0.1 jiraiyaredis 保存后 点击 以管理员身份重试 Linux 环境 Root 用户修改 /etc/hosts ip jiraiyamysql ip jiraiyaredis ### 工作流程 1、理解需求 重点：理解透彻、不懂得抓紧问，完成后需要复述 2、明确设计 重点： （1）：简单模块: a）明确设计方案(需研发组长确认) b）实现思路(需研发组长确认)：安全编程、正常异常情况处理 c）数据库设计(需研发负责人确认)；不确认不开发 （2）：复杂模块（包含简单模块的所有步骤） 明确设计方案：需提供流程图、类图的相关资料、如需新技术请提供技术调研结果（5w2h） 实现思路：简单的性能测试（峰值） 数据库设计：评审讨论 技术评审 3、待办事项 （1）记录需求、待优化项、以及FAQ （2）记录自认为重要的内容（好记性不如烂笔头） （3）待办事项分短期和长期进行组织分类 短期：实时更新（紧急度较高） 长期：长期跟踪优先级较低（重要不紧急） （4）事无巨细 不要有工作遗漏！ 4、时间管理四象限（依赖于待办事项） 紧急重要 时间分配20% 紧急不重要 时间分配10% 不紧急重要 时间分配70% 不紧急不重要 时间分配0 5、工期、时间点 （依赖于时间管理） （1）开发要有计划 明确工期于时间点 （2）如延期请务必提交前告知，并告知原因与延期时间点 6、验收确认 （1）需要自测：不能有过多低级或明显的BUG （2）需提交给研发组长确认答疑 （3）提交测试 ### 1、部署说明：修改application-dev.yml配置文件信息如下 （1）ht:serverBaseUrl、loginUrl （2）es:host、port （3）dm:url、username、password