Skip to content

从功能到代码:跟着「新增用户」走一遍 ​

这一页是一次完整示范:从产品能力出发,经功能卡 → 接口索引 → 数据字典,落到一个 Controller 方法、一个 Service、一张表,最后回到「怎么自己验证」。全程用真实文件与行号,读完可以照着再走一遍别的功能。

0. 路线图 ​

步你在哪一层看什么本次的落点
1产品层能力清单里有没有这个功能能力地图 的 SYS-USER-01
2功能卡权限点、接口、表、坑,一页看完SYS-USER-01
3接口索引全量接口与权限点的机器清单system 接口清单
4数据字典表与实体字段system 数据字典
5代码Controller → Service → Mapper → DO本文第 3–6 节
6验证权限、租户、日志是否都生效本文第 7 节

1. 产品侧:这个功能叫什么 ​

能力地图里它是 SYS-USER-01「用户管理」,状态 ✅(pmforge-module-system 参与构建)。功能卡上写着它的四件事:

  • 权限点:system:user:create、system:user:update、system:user:delete、system:user:query、system:user:export、system:user:import
  • 接口:/system/user/create、/update、/delete、/get、/page、/export、/import
  • 表:system_users、system_user_role、system_user_post
  • 坑:导入走 @ApiAccessLog(operateType = IMPORT);分页查询会二次装配部门信息

2. 接口索引与数据字典:机器生成的那一层 ​

system 接口清单 由 script/docs/scan-knowledge.mjs 扫描 @RestController 生成,每一行是「方法 + 路径 + 权限点 + 源文件行号」。/system/user/create 这一行会把你送到 UserController.java 的对应行。

system 数据字典 则把 @TableName 与 sql/mysql/pmforge.sql 的 CREATE TABLE 对齐:system_users 的字段、类型、注释都在这里。两者都是生成物,代码改了没重新生成,npm run docs:check 会让 CI 失败。

3. 入口:Controller ​

pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java

行内容
#L52@PostMapping("/create") —— 路径与类上的 /system/user 拼成 /system/user/create
#L54@PreAuthorize("@ss.hasPermission('system:user:create')") —— 功能权限校验,ss 是 SecurityFrameworkService
#L55public CommonResult<Long> createUser(@Valid @RequestBody UserSaveReqVO reqVO) —— 显式返回 CommonResult,不靠全局包装

参数对象 UserSaveReqVO 在 controller/admin/user/vo/user/UserSaveReqVO.java,字段校验注解(@NotBlank、@Email 等)在这一层生效。

4. 业务:Service ​

pmforge-module-system/src/main/java/com/pmforge/module/system/service/user/AdminUserServiceImpl.java

行内容
#L99public Long createUser(UserSaveReqVO createReqVO) 实际业务入口
#L108validateUserForCreateOrUpdate(...) 查用户名/手机/邮箱唯一性(#L402 是该方法定义)
#L114userMapper.insert(user) 写主表
#L117userPostMapper.insertBatch(...) 写用户-岗位关联表

user 是 UserConvert 从 VO 转换来的 DO,密码在此前用 BCryptPasswordEncoder 加密。方法上有 @Transactional(rollbackFor = Exception.class),主表与关联表同事务。

5. 持久化:Mapper 与 DO ​

位置内容
pmforge-module-system/src/main/java/com/pmforge/module/system/dal/mysql/user/AdminUserMapper.java#L14public interface AdminUserMapper extends BaseMapperX<AdminUserDO>,继承 BaseMapperX 直接拿到 insert、selectPage、selectJoinPage 等
pmforge-module-system/src/main/java/com/pmforge/module/system/dal/dataobject/user/AdminUserDO.java#L22@TableName(value = "system_users", autoResultMap = true)(SQL Server 里 system_user 是关键字,所以表名带 s)
同文件 #L29public class AdminUserDO extends TenantBaseDO —— 带 tenant_id,插入时由租户拦截器补值

6. 数据库:表与权限点 ​

  • 建表语句:sql/mysql/pmforge.sql#L5021(CREATE TABLE system_users),字段与注释可在数据字典对照。
  • 权限点种子:sql/mysql/pmforge.sql#L1927 的 system_menu 批量 INSERT 里有 system:user:create —— 菜单表既是导航也是权限点来源,@PreAuthorize 校验的就是这个字符串。
  • 租户与数据权限:system_users 的 tenant_id 由 TenantLineInnerInterceptor 自动补条件;部门范围过滤走 数据权限。

7. 验证:怎么确认这条链真的通了 ​

  1. 接口层:启动后打开 http://localhost:48080/doc.html,找「系统管理 → 用户」,调 /system/user/create,返回 {"code":0,"data":<id>}。
  2. 权限层:用一个没有 system:user:create 的账号调同一接口,应返回 403 而不是 200;给角色补上该权限点后立刻生效(权限来自缓存,PermissionServiceImpl 负责刷新)。
  3. 租户层:用租户 A 的账号创建用户,再查 system_users,tenant_id 应为 A;切到租户 B 查不到这条记录。
  4. 日志层:调用后查 infra_api_access_log,应有一条 request_url=/system/user/create 的记录(@ApiAccessLog 默认记录写操作)。
  5. 一致性:改动 Controller 后跑 npm run docs:gen,接口索引应出现新行;不重新生成就提交,npm run docs:check 会失败。

8. 把这个套路用到别的功能 ​

  • 任意功能卡 → 第 2 节「接口与权限点」找到入口方法 → 第 4 节「代码定位」直达行号。
  • 只有权限点、没有卡时:用索引:按代码找功能反查权限点或表名。
  • 想动手:从练习与自测的练习 1、2 开始,都是这条链路的变形。