规范

规范就像软件开发的地图和指南，帮助团队成员在项目旅程中找到正确的方向。它们为代码的组织、命名和风格设立了框架，使得整个团队能够以更加一致的方式合作。通过规范，我们可以避免陷入混乱和混乱的境地，并确保我们的代码库保持清晰、易于理解和可维护。

以下规范看起来有可能比较多，但是我们代码生成器基本都帮助我们实现了。

后端

1. 项目结构

我们以表teacher_statistics为例，其业务代码结构如下：

以后新业务与teacher_statics同理，在com.sz.admin目录下创建业务相关包名，并同时遵循下述结构。

虽然看起来目录结构比较多，但我们不用担心，代码生成器很容易帮我们创建它们，并且可以根据自己的实际需求灵活生成所需文件。

shell

sz-boot-parent/sz-service/sz-service-admin/
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── sz
│   │   │           ├── admin
│   │   │           │   ├── system											# rbac系统相关代码等都存放到此包下
│   │   │ 			│   │   │  ...
│   │   │           │   └── teacher											# teacher_statstics 表抽取包名，存放所有和teacher相关的业务
│   │   │           │       ├── controller									# controller层
│   │   │           │       │   └── TeacherStatisticsController.java				
│   │   │           │       ├── mapper
│   │   │           │       │   └── TeacherStatisticsMapper.java			# mybatis mapper
│   │   │           │       ├── pojo										# pojo层
│   │   │           │       │   ├── dto
│   │   │           │       │   │   ├── TeacherStatisticsCreateDTO.java		# DTO add
│   │   │           │       │   │   ├── TeacherStatisticsImportDTO.java		# DTO 导入
│   │   │           │       │   │   ├── TeacherStatisticsListDTO.java		# DTO 列表查询条件
│   │   │           │       │   │   └── TeacherStatisticsUpdateDTO.java		# DTO update
│   │   │           │       │   ├── po
│   │   │           │       │   │   └── TeacherStatistics.java				# PO 数据库实体映射
│   │   │           │       │   └── vo
│   │   │           │       │       └── TeacherStatisticsVO.java
│   │   │           │       └── service										# service层
│   │   │           │           ├── impl
│   │   │           │           │   └── TeacherStatisticsServiceImpl.java
│   │   │           │           └── TeacherStatisticsService.java
│   │   └── resources
│   │       ├── ...
│   │       ├── mapper
│   │       │   ├── system
│   │       │   ├── ...
│   │       │   └── teacher													# mybatis mapperXml
│   │       │       └── TeacherStatisticsMapper.xml

2. 分层

在sz-admin框架中，我们采用DTO、VO和PO来组织POJO类，以优化数据管理和传输：

DTO（数据传输对象）：（Data Transfer Object）专为服务层与控制器间的数据交换设计，仅包含数据属性，不涉及业务逻辑。
VO（视图对象）：定制化数据结构，用于向用户界面传递信息。VO可以基于DTO进行扩展，包含简化或特定格式的数据，并可能集成少量业务逻辑以满足展示需求。
PO（持久化对象）：代表数据库中的持久化数据模型，与数据库表结构直接对应，属性映射数据库字段。

3. 时间格式

在创建数据表时，除非有特定需求，我们通常将时间字段设置为datetime类型，这在Java中对应于LocalDateTime或LocalDate类型。

无需担心时间格式的解析问题，因为我们的框架已经在sz-common模块中的JacksonConfiguration.java^[1]类中提供了相应的处理。

4. 主键自增ID、关联ID

框架规定，所有主键自增ID（int）、关联ID（int） 在java中都以 Long 类型进行映射。

5. Web API

我们的Web API严格遵循RESTful API设计原则，以确保高效和一致的资源管理。以下是API路由和操作的概览：

如：

Method	Router	CRUD	描述
POST	/teacher-statics	新增	用于创建新的教师统计数据
PUT	/teacher-statics	修改	用于更新教师统计数据。
DELETE	/teacher-statics	删除	用于删除教师统计数据。
GET	/teacher-statics	查询、分页查询	用于检索教师统计数据列表，支持分页查询。
GET	/teacher-statics/{id}	详情	用于获取指定ID的教师统计数据详情。
POST	/teacher-statics/import	导入	用于执行教师统计数据的批量导入。
POST	/teacher-statics/export	导出	用于执行教师统计数据的批量导出。

6. Service 接口命名规范

在teacher_staticstics表的业务逻辑中，我们遵循以下接口方法命名规则，以确保代码的清晰和一致性：

java

public interface TeacherStatisticsService extends IService<TeacherStatistics> {

    // 新增
    void create(TeacherStatisticsCreateDTO dto);

    // 修改
    void update(TeacherStatisticsUpdateDTO dto);

    // 分页
    PageResult<TeacherStatisticsVO> page(TeacherStatisticsListDTO dto);

    // 列表（不分页）
    List<TeacherStatisticsVO> list(TeacherStatisticsListDTO dto);

    // 删除
    void remove(SelectIdsDTO dto);

    // 详情
    TeacherStatisticsVO detail(Object id);

    // 导入
    void importExcel(MultipartFile file);

    // 导出
    void exportExcel(TeacherStatisticsListDTO dto, HttpServletResponse response);
}

7. Swagger注解

我们的框架遵循Swagger 3和OpenAPI Specification (OAS) 3.0标准，要求在Controller方法和POJO类上适当使用注解，以确保API的自文档化和规范性。

例如，您可以这样使用注解：

java

// controller.java
@Tag(name =  "教师统计总览表")
public class TeacherStatisticsController  {
    
    @Operation(summary = "新增")
    public ApiResult create(@RequestBody TeacherStatisticsCreateDTO dto) {
        teacherStatisticsService.create(dto);
        return ApiResult.success();
    }
    
	// 二进制文件上传特殊样式
    @Operation(summary = "导入")
    @Parameters({
      @Parameter(name = "file", description = "上传文件", schema = @Schema(type = "string", format = "binary"), required = true),
    })
    public void importExcel(MultipartFile file) {
        teacherStatisticsService.importExcel(file);
    }
    
    // ...
}

java

// DTO.java、PO.java、VO.java
@Data
@Schema(description = "TeacherStatistics添加DTO")
public class TeacherStatisticsCreateDTO {

   @Schema(description =  "统计年限")
   private String year;

   @Schema(description =  "统计月份")
   private String month;

   @Schema(description =  "统计年月")
   private String duringTime;

   @Schema(description =  "教师id")
   private String teacherId;

   @Schema(description =  "讲师区分类型")
   private Integer teacherCommonType;

   @Schema(description =  "授课总数")
   private Integer totalTeaching;

   @Schema(description =  "服务班次数")
   private Integer totalClassCount;

   @Schema(description =  "课时总数")
   private BigDecimal totalHours;

   @Schema(description =  "核对状态")
   private Integer checkStatus;

   @Schema(description =  "核对时间")
   @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
   private LocalDateTime checkTime;

   @Schema(description =  "最近一次同步时间")
   @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
   private LocalDateTime lastSyncTime;

   @Schema(description =  "备注")
   private String remark;

}

生成API文档 UI 如下 Swagger3文档效果-Knife4j

8. @Autowired 注解

框架中如无特殊情况禁止使用@Autowired注解！！如需引入bean可使用如下两种方式：

使用 @RequiredArgsConstructor：在类的构造函数中声明 final 类型的依赖，Lombok 会自动生成构造函数，并自动注入对应的 bean。例如：

java

 @RequiredArgsConstructor
public class TeacherStatisticsController {
	private final TeacherStatisticsService teacherStatisticsService;
}

使用 @Resource 注解：通过 @Resource 注解直接注入对应的 bean。例如：

java

public class TeacherStatisticsController {
	@Resource
    private TeacherStatisticsService teacherStatisticsService;
}

9. 接口鉴权

在我们的框架中，我们强烈建议为Controller接口方法明确指定权限要求，除非有特定的业务需求。这种做法不仅有助于增强系统的安全性，还能确保操作的合规性。

以下是如何使用 @SaCheckPermission 注解来定义接口方法的权限范围的示例代码：

java

public class SysRoleController {
    
    // 仅允许拥有 `sys.role.create_btn` 权限标识的用户或超级管理员角色访问。
    @Operation(summary = "新增角色")
    @SaCheckPermission(value = "sys.role.create_btn", orRole = GlobalConstant.SUPER_ROLE)
    public ApiResult create(@Valid @RequestBody SysRoleAddDTO dto) {
        sysRoleService.create(dto);
        return ApiResult.success();
    }

    // 需要同时具备 `sys.role.setting_btn` 和 `sys.role.update_btn` 权限标识的用户或超级管理员角色才能访问。
    @Operation(summary = "查询角色菜单信息")
    @SaCheckPermission(value = {"sys.role.setting_btn", "sys.role.update_btn"}, mode = SaMode.AND, orRole = GlobalConstant.SUPER_ROLE)
    @GetMapping("/menu")
    public ApiResult findRoleMenuByRoleId(@NotZero @RequestParam Integer roleId) {
        return ApiPageResult.success(sysRoleMenuService.queryRoleMenu(roleId));
    }

    // 更多方法...
}

在实际业务中，我们通常会遇到三种鉴权场景：

明确鉴权：对于需要进行权限控制的按钮（或接口），应使用 @SaCheckPermission 注解明确指定所需的权限标识。
无需鉴权：对于不需要鉴权的接口，如登录接口，可以在Controller上使用 @SaIgnore 注解，或在 sa-token.yml 配置文件中通过 router.whitelist 配置来实现。
有条件的鉴权：对于某些公共查询接口，虽然不需要验证具体的权限标识，但要求用户必须已经登录。在这种情况下，无需在Controller层添加额外的鉴权处理。

WARNING

数据权限的核心功能依赖于@SaCheckPermission注解来实现。为了确保数据权限的正常运行，请确保所有需要实现权限控制的Controller层都正确配置了该注解。这将帮助系统自动识别并应用相应的权限规则。

前端

1. 项目结构

同样，我们以表teacher_statistics为例，其业务代码结构如下：

shell

sz-admin/
├── api
│   ├── ...
│   ├── interface											# ts对象结构，类似于 Java 实体对象
│   │   ├── system											
│   │   │   ├── ...
│   │   ├── teacher											# teacher_statstics 表抽取包名，存放所有和teacher相关的业务			
│   │   │   └── teacherStatistics.ts						# 对象实体
│   │   └── ...
│   └── modules
│       ├── system
│       │   ├── ...
│       ├── teacher											# teacher_statstics 表抽取包名，存放所有和teacher相关的业务
│       │   └── teacherStatistics.ts						# API路由
│   │   └── ...
├── ...
└── views													# 项目所有页面
    ├── system
    │   ├── ...
    ├── teacher												# teacher_statstics 表抽取包名，存放所有和teacher相关的业务
    │   └── teacherStatistics
    │       ├── components									# 页面组件包
    │       │   └── TeacherStatisticsForm.vue				# Form组件（新增、编辑）
    │       └── index.vue									# 主页面
    └── ...

2. 按钮鉴权

在我们的开发框架中，对于按钮控件，除非有特定的业务需求，否则必须明确定义它们的权限级别。

例如，以下是使用v-auth指令来指定权限的代码示例：

TIP

v-auth 指令有三种使用方式：

单一权限：
具有指定字符串内的权限
vue
```
v-auth="'sys.menu.create_btn'"
```
1

多条件AND：

必须同时具有conditions数组包含的权限

vue

v-auth="[{ type: 'and', conditions: ['sys.role.setting_btn', 'sys.role.update_btn'] }]"

多条件OR：

具有conditions数组内的任一权限

vue

v-auth="[{ type: 'or',  conditions: ['sys.user.unlock_btn','sys.user.role_set_btn','sys.user.delete_btn' ] }]"

vue

<template>
  <div class="table-box"> 
      
    <ProTable
      ref="proTableRef"
      title="教师统计"
      :indent="20"
      :columns="columns"
      :search-columns="searchColumns"
      :request-api="getTableList"
      row-key="id"
    >
      <!-- 表格 header 按钮 -->
      <template #tableHeader="scope">
        <el-button
          type="primary"
          v-auth="'teacher.statistics.create'" 
          :icon="CirclePlus"
          @click="openAddEdit('新增教师统计')"
        >
          新增
        </el-button>
    	...
        <el-button
          v-auth="'teacher.statistics.remove'"
          type="primary"
          link
          :icon="Delete"
          @click="deleteInfo(row)"
        >
          删除
        </el-button>
      </template>
    </ProTable>
  </div>
</template>
...

3. 代码提交前检查

为了确保项目的长期可持续性和可维护性，我们制定了以下代码提交前的检查流程。请遵循以下步骤，以确保您的代码符合项目标准：

类型检查 (type-check)
在提交代码前，请运行 TypeScript 类型检查，以确保代码的类型安全。避免使用 any 类型（“any script编程”），因为这会削弱类型系统的优势。如果在构建阶段发现类型错误，构建过程将失败。
shell
```
pnpm run type-check
```
1
代码风格检查 (lint)
使用 ESLint 进行代码风格检查，确保代码符合项目的风格规范。这有助于保持代码的一致性和可读性。
shell
```
pnpm run lint
```
1
代码格式化 (format)
在提交之前，对代码进行格式化，以确保其整洁和一致。这有助于减少因格式问题引起的代码审查。
shell
```
pnpm run format
```
1

我们推荐使用集成开发环境（IDE）来自动化上述流程。大多数现代编辑器都支持快捷方式或插件来执行这些操作。以下是在 WebStorm 中执行这些操作的示例：

package.json 代码检测命令

打开package.json 分别运行划线部分左侧头部的运行图标即可。

位于/sz-common/sz-common-core模块下，包com.sz.core.common.configuration ↩︎

规范 ​

后端 ​

1. 项目结构 ​

2. 分层 ​

3. 时间格式 ​

4. 主键自增ID、关联ID ​

5. Web API ​

6. Service 接口命名规范 ​

7. Swagger注解 ​

8. @Autowired 注解 ​

9. 接口鉴权 ​

前端 ​

1. 项目结构 ​

2. 按钮鉴权 ​

3. 代码提交前检查 ​

规范

后端

1. 项目结构

2. 分层

3. 时间格式

4. 主键自增ID、关联ID

5. Web API

6. Service 接口命名规范

7. Swagger注解

8. @Autowired 注解

9. 接口鉴权

前端

1. 项目结构

2. 按钮鉴权

3. 代码提交前检查