demo/README.md

# FxBoot

## 一、开发准备

### 1.开发工具：IDEA

### 2.安装插件

#### google-java-format（谷歌代码规范插件）

Preferences->Other Settings->google-java-format Settings

![image.png](https://s1.ax1x.com/2022/08/29/vf9aKP.png)

#### save actions（保存代码自动格式化插件）

Preferences->Other Settings->Save Actions

![image.png](https://s1.ax1x.com/2022/08/29/vf9Nvt.png)

#### Alibaba Java Coding Guidelines（阿里编码规范插件）

#### JRebel and XRebel（热加载插件）

下载旧版本手动安装[JRebel and XRebel 2022.4.1](https://plugins.jetbrains.com/plugin/4441-jrebel-and-xrebel/versions)

跟随JRebel setup guide导航一步步设置，激活插件可前往[jrebel.qekang.com](http://jrebel.qekang.com/)获取一键地址，例如

```
地址：https://jrebel.qekang.com/f9754b17-23dd-4915-a0c6-4fafef7e46e0
邮箱：随意
```

而后可使用该插件代替原有的启动按钮，修改代码后无需重启即可生效

![zUHjzT.png](https://s1.ax1x.com/2022/11/28/zUHjzT.png)

## 二、快速入门

### 1.修改项目

配置根目录的`gradle.properties`，修改项目名、版本号(有必要的话)。

```shell
projectName=fx-boot
projectVersion=1.0.0
```

### 2.导入数据库

新建fxboot数据库，字符集选择`utf8mb4`，排序规则选择`utf8mb4_general_ci`

将根目录下的`db/fxboot.sql`导入到新建的数据库中

### 3.修改配置

> 具体可查阅 `app/resources/application.yml`

若数据库为`127.0.0.1:3306`且账号密码都为`root`，则可跳过此步骤

否则可配置环境变量(如何配置请自行搜索)，支持环境变量如下

#### mysql

- FXBOOT_MYSQL_HOST
- FXBOOT_MYSQL_PORT
- FXBOOT_MYSQL_USER
- FXBOOT_MYSQL_PASSWORD

#### redis

- FXBOOT_REDIS_HOST
- FXBOOT_REDIS_PORT
- FXBOOT_REDIS_DATABASE

### 4.运行项目

在app模块中的FxBootApplication启动类上右键运行，或者在IDE右上角找到启动按钮，点击启动

### 5.初始化提交环境

> 需要安装npm，且安装pnpm（未安装可执行`npm i -g pnpm`）

```shell
pnpm i
```

### 6.提交代码

#### 6.1 开启暂存区

![img.png](https://s1.ax1x.com/2022/12/08/z2NDdx.png)

#### 6.2 暂存想要提交的文件

每次暂存前，请审查一遍自己变动的，降低审查被驳回的概率

![img.png](https://s1.ax1x.com/2022/12/08/z2NfOA.png)

#### 6.3 提交已暂存的文件

具体提交规范查看相关文档

```shell
pnpm cz
```

## 三、开发规范

### 1.结构分层

分controller/entity/mapper/service四个层次，复杂模块需再次分级，如

- controller/system
- controller/base

### 2.注释

- 类上需`author`和`date`
  ```java
  /**
   * @author huanghs@zgfxrc.cn
   * @date 2021.11.22
   */
  ```

- 方法上需通过/**回车自动生成注释，并补齐入参和返回的说明。
  ```java
  /**
   * 不为empty则执行方法，empty包含null、数组队列空等情况
   *
   * @param obj 对象
   * @param apply 方法(传入对象)
   */
  ```
- 若方法添加时间与类不一致，需要增加如`@date 2021.11.22`说明。
  ```java
  /**
   * 不为empty则执行方法，empty包含null、数组队列空等情况
   *
   * @param obj 对象
   * @param apply 方法(传入对象)
   * @date 2021.11.22
   */
  ```
- 若且此类为他人创建，而你创建了方法，则需要增加如`@date 2021.11.22 your@email.com`说明
  ```java
  /**
   * 不为empty则执行方法，empty包含null、数组队列空等情况
   *
   * @param obj 对象
   * @param apply 方法(传入对象)
   * @date 2021.11.22 your@email.com
   */
  ```

### 3.entity规范

注释注解

```java
/**
 * 用户表
 *
 * @author huanghs@zgfxrc.cn
 * @date 2021.11.22
 */
@Data
@ApiModel("用户表")
@EqualsAndHashCode(callSuper = true)
public class User extends Model<User> {
}
```

关联表无主键

```java
public class User extends Model<User> {
}
```

有主键

```java
public class User extends BaseModel<User> {
}
```

有主键且需要租户过滤

```java
public class User extends BaseModelWithTenant<User> {
}
```

### 4.controller规范

需要使用`@Api`说明业务, 其内方法需`@ApiOperation`说明具体功能, 通过`@Permission`指定访问接口所需权限
控制层不写业务逻辑，所有代码需封装在Service中，控制层只需要`service.runYourFunc()`调用封装的业务方法。

```java
/**
 * @author huanghs@zgfxrc.cn
 * @date 2021.11.22
 */
@RestController
@Api(tags = "用户管理")
@RequestMapping("sys/user")
public class SysUserController {
  final SysUserService sysUserService;

  // 最终会需要 sys_user_view 权限
  @Permission("sys_user_view")
  @ApiOperation("查询")
  @PostMapping
  public void get() {
    sysUserService.runYourFunc();
  }
}
```

### 5.RequestMapper

(1).遵循小写单词，多单词由/隔开，如`@RequestMapping("sys/user")`
(2).遵循POST规范，所有接口使用`PostMapping`定义
(3).传参只能通过params传递`void func(Entity entity)`或者body传递`void func(@RequestBody Entity entity)`
(4).路由传参通过`@PostMapping("/get/one/{id}")`，通过`@PathVariable Long id`接收

### 6.Service规范

- 在Service中，不能调用本类的其他方法，避免aop失效
- 参数校验使用`Validate.nonNull(req.userId,"用户id不能为空")`等校验值和给出错误提示

## 四、部署

### 1.配置镜像

配置根目录`deploy.sh`的镜像仓库地址，并且在每次发布版本时，只需要修改版本号 `VERSION` 即可。

```properties
HUB=registry.cn-hangzhou.aliyuncs.com/rsjst
VERSION=1.0.0
```

### 2.打包

执行脚本，将会自动构建镜像`镜像仓库地址/项目名:版本号`并推送到仓库中，
例如 `registry.cn-hangzhou.aliyuncs.com/rsjst/fx-boot:1.0.0`

```shell
sh deploy.sh
```

### 3.部署

配置dockerSwarm的stack中的image为打包的镜像即可，例如

```yml
version: '3.7'
services:
  fx-boot:
    image: registry.cn-hangzhou.aliyuncs.com/rsjst/fx-boot:1.0.0
    ports:
      - '8020:8020'
    environment:
      # 数据库配置
      FXBOOT_MYSQL_HOST: 192.168.1.1
      FXBOOT_MYSQL_PORT: 3306
      FXBOOT_MYSQL_USER: root
      FXBOOT_MYSQL_PASSWORD: 123456
      FXBOOT_MYSQL_TABLE: fxboot

      # Redis配置
      FXBOOT_REDIS_HOST: 127.0.0.1
      FXBOOT_REDIS_PORT: 6379
      FXBOOT_REDIS_DATABASE: 1
      FXBOOT_REDIS_PASSWORD: 123456

      # *配置等待数据库启动完毕再启动应用
      WAIT_FOR: 192.168.1.1:3306
      WAIT_TIMEOUT: 60

      # *配置active值，若增加模块仍需要往后添加，避免无法读取到子模块的配置，例如application-upms.yml
      SPRING_PROFILES_ACTIVE: prod,upms,recruit

      # *存储配置，若不知道填什么向上级要
      MINIO_ACCESS_KEY: xxx
      MINIO_SECRET_KEY: xxx
      MINIO_BUCKET_NAME: xxx

    # 下述配置实现热更新，不需要可去除
    deploy:
      mode: replicated
      replicas: 1
      resources:
        limits:
          cpus: '0.75'
        reservations:
          cpus: '0.50'
      update_config:
        delay: 5s
        order: start-first
```

## 五、相关文档

### 1.鉴权功能

[secret](https://github.com/seepine/secret/)

### 2.统一返回体包装

[wrap-spring-boot-starter](https://seepine.com/springboot/wrap/)

### 3.工具类

[tool](https://github.com/seepine/tool/)

### 4.ORM

[mybatis-plus](https://baomidou.com/)

### 5.部署相关

[构建多平台Docker镜像](https://seepine.com/docker/build-multi-platform-image/)

[Docker nginx conf 使用环境变量](https://seepine.com/docker/nginx/)

### 6.协同开发

[Git多分支开发](https://seepine.com/dev/git/multi-branch/)