简介
Sz Admin ，一个基于 Spring Boot 3、JDK21、Vue 3 和 Element-Plus 的开源后台管理框架，致力于为您提供一个流畅、直观且功能强大的开发框架。它不仅融合了最新的技术趋势，而且通过精心设计，确保了系统的简洁性和高效，让使用者可以专注业务。
在线体验
- 官网地址：https://szadmin.cn
- 文档地址：https://szadmin.cn/md/Help/doc/start.html
- 预览地址：https://preview.szadmin.cn
- 代码仓库：
- 前端：
- 后端：
- Github：sz-boot-parent
- Gitee：sz-boot-parent
- 部署：
规范
规范就像软件开发的地图和指南，帮助团队成员在项目旅程中找到正确的方向。它们为代码的组织、命名和风格设立了框架，使得整个团队能够以更加一致的方式合作。通过规范，我们可以避免陷入混乱和混乱的境地，并确保我们的代码库保持清晰、易于理解和可维护。
<font color=blue>不要担心！</font> 以下规范看起来有可能比较多，但是我们代码生成器基本都帮助我们实现了。
后端
1. 项目结构
我们以表teacher_statistics为例，其业务代码结构如下：
以后新业务与<u>teacher_statics</u>同理，在com.sz.admin目录下创建业务相关包名，并同时遵循下述结构。
虽然看起来目录结构比较多，但我们不用担心，代码生成器很容易帮我们创建它们，并且可以根据自己的实际需求灵活生成所需文件。
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表的业务逻辑中，我们遵循以下接口方法命名规则，以确保代码的清晰和一致性：
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的自文档化和规范性。
例如，您可以这样使用注解：
// 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);
}
// ...
}
// 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 如下
8. @Autowired 注解
框架中如无特殊情况禁止使用@Autowired注解！！如需引入bean可使用如下两种方式：
- 使用 @RequiredArgsConstructor：在类的构造函数中声明 final 类型的依赖，Lombok 会自动生成构造函数，并自动注入对应的 bean。例如：
@RequiredArgsConstructor
public class TeacherStatisticsController {
private final TeacherStatisticsService teacherStatisticsService;
}
-
使用 @Resource 注解：通过
@Resource注解直接注入对应的 bean。例如：
public class TeacherStatisticsController {
@Resource
private TeacherStatisticsService teacherStatisticsService;
}
9. 接口鉴权
在我们的框架中，Controller 接口方法应明确其权限要求，除非存在特定的业务需求。这有助于确保安全性和合规性。
以下是使用 @SaCheckPermission 注解来指定接口方法权限范围的示例代码：
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));
}
}
前端
1. 项目结构
同样，我们以表teacher_statistics为例，其业务代码结构如下：
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 指令有三种使用方式：
单一权限：
具有指定字符串内的权限
v-auth="'sys.menu.create_btn'"多条件AND：
必须同时具有conditions数组包含的权限
v-auth="[{ type: 'and', conditions: ['sys.role.setting_btn', 'sys.role.update_btn'] }]"多条件OR：
具有conditions数组内的任一权限
v-auth="[{ type: 'or', conditions: ['sys.user.unlock_btn','sys.user.role_set_btn','sys.user.delete_btn' ] }]"
<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编程”），因为这会削弱类型系统的优势。如果在构建阶段发现类型错误，构建过程将失败。pnpm run type-check -
代码风格检查 (
lint)使用 ESLint 进行代码风格检查，确保代码符合项目的风格规范。这有助于保持代码的一致性和可读性。
pnpm run lint -
代码格式化 (
format)在提交之前，对代码进行格式化，以确保其整洁和一致。这有助于减少因格式问题引起的代码审查。
pnpm run format
我们推荐使用集成开发环境（IDE）来自动化上述流程。大多数现代编辑器都支持快捷方式或插件来执行这些操作。以下是在 WebStorm 中执行这些操作的示例：
打开package.json 分别运行划线部分左侧头部的运行图标即可。
-
位于/sz-common/sz-common-core模块下，包com.sz.core.common.configuration ↩
