Skip to content

练习与自测 ​

练习都可回滚,做完用 git checkout -- <路径> 还原(新增文件直接删除)。

练习 1:追一条新增用户链路 ​

  • 目标:从 Controller 追到 Mapper,说清每层做了什么。
  • 前置:请求处理链路、用户新增卡
  • 步骤:
    1. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L54 看权限点,#L56 看 Controller 只接收参数并转调 Service。
    2. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/service/user/AdminUserServiceImpl.java#L99 看租户账号数校验,#L114 看 userMapper.insert(user)。
    3. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/dal/mysql/user/AdminUserMapper.java#L16 看 selectByUsername,在 pmforge-module-system/src/main/java/com/pmforge/module/system/dal/dataobject/user/AdminUserDO.java#L22 确认表名 system_users。
    4. 用 Authorization: Bearer test1、tenant-id: 1 调 POST /admin-api/system/user/create,body 至少含 username、password、deptId。
  • 验收:响应 code=0 且 data 为新 id;system_users 多一行,password 是 BCrypt 串而不是明文;控制台能看到 insert SQL。
  • 延伸:给 UserSaveReqVO 加一个字段,沿 VO→DO→表补完并重新调用。

练习 2:加一个只读接口 ​

  • 目标:新增 GET /system/user/get-by-username,并让权限点真正生效。
  • 前置:鉴权与权限点、system 模块
  • 步骤:
    1. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L150 后加方法:@GetMapping("/get-by-username")、@PreAuthorize("@ss.hasPermission('system:user:read')"),方法体调 userService.getUserByUsername(username) 并用 BeanUtils.toBean 转 UserRespVO(补 import)。
    2. 在菜单 100 下加按钮:INSERT INTO system_menu (name, permission, type, sort, parent_id) VALUES ('按用户名查询','system:user:read',3,9,100);;type=3 是按钮,非超管还要通过 system_role_menu 给角色授权。
    3. mvn -B -ntp -Dmaven.test.skip=true package 后重启,调 GET /admin-api/system/user/get-by-username?username=admin。
  • 验收:code=0 且返回用户;把 @PreAuthorize 的权限点改成未授权值后,同一请求的响应体 code=403。
  • 延伸:给接口加 @Operation 与参数校验,再跑 npm run docs:gen 看它进入 API 页。

练习 3:用代码生成器建表跑通 CRUD ​

  • 目标:从一张新表生成后端 CRUD 与菜单 SQL,并跑通新增、分页。
  • 前置:代码生成闭环、infra 模块
  • 步骤:
    1. 在 pmforge-jdk8 执行下面建表 SQL,并插一条代码生成数据源记录(infra_data_source_config 默认没有种子数据)。
sql
CREATE TABLE `infra_training_note` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',
  `title` varchar(100) NOT NULL COMMENT '标题',
  `content` varchar(500) DEFAULT NULL COMMENT '内容',
  `dept_id` bigint DEFAULT NULL COMMENT '部门编号',
  `creator` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updater` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否删除',
  PRIMARY KEY (`id`)
) COMMENT='练习笔记表';

INSERT INTO infra_data_source_config (name,url,username,password,creator,create_time,updater,update_time,deleted)
VALUES ('local','jdbc:mysql://127.0.0.1:3306/pmforge-jdk8?useSSL=false&serverTimezone=Asia/Shanghai','root','123456','1',NOW(),'1',NOW(),b'0');
  1. 调 POST /admin-api/infra/codegen/create-list,body 为 {"dataSourceConfigId":16,"tableNames":["infra_training_note"]};16 是干净库的起始自增值,若已被占用就换成 SELECT id FROM infra_data_source_config WHERE name='local' 的结果。接口与权限点见 pmforge-module-infra/src/main/java/com/pmforge/module/infra/controller/admin/codegen/CodegenController.java#L94,表名拆分规则见 pmforge-module-infra/src/main/java/com/pmforge/module/infra/service/codegen/inner/CodegenBuilder.java#L116。
  2. 调 GET /admin-api/infra/codegen/download?tableId=<上一步返回的 id> 得到 zip;解压后把 pmforge-module-infra/pmforge-module-infra-server/ 这一层扁平化为 pmforge-module-infra/,Java 放 src/main/java,Mapper XML 放 src/main/resources;路径拼接见 pmforge-module-infra/src/main/java/com/pmforge/module/infra/service/codegen/inner/CodegenEngine.java#L661。
  3. 执行 zip 里的菜单 SQL,再运行 mvn -B -ntp -Dmaven.test.skip=true package 并重启;调 POST /admin-api/infra/training-note/create 与 GET /admin-api/infra/training-note/page?pageNo=1&pageSize=10。
  • 验收:create 返回新 id;page 的 total>=1 且包含刚插入的标题;mvn 构建通过。
  • 延伸:给表加 status 字段后点“同步表结构”,比较重新生成的 VO 差异。

练习 4:用 @TenantIgnore 观察租户放行 ​

  • 目标:看清“方法上的 @TenantIgnore 只放行方法内的 SQL,不会自动把 URL 加进 ignore-urls”。
  • 前置:多租户、租户卡
  • 步骤:
    1. 直接插一个租户 2 的用户作对照:INSERT INTO system_users (id,username,password,nickname,dept_id,post_ids,status,deleted,tenant_id) VALUES (900001,'tenant2','x','tenant2',103,'[]',0,b'0',2);。
    2. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/TrainingTenantController.java 新建控制器,注入 AdminUserMapper,方法加 @GetMapping("/count-all")、@PermitAll、@TenantIgnore,返回 adminUserMapper.selectCount(null);注解定义见 pmforge-framework/pmforge-spring-boot-starter-biz-tenant/src/main/java/com/pmforge/framework/tenant/core/aop/TenantIgnore.java#L30。
    3. 带 tenant-id: 1 与 Authorization: Bearer test1 调 GET /admin-api/system/training-tenant/count-all;再去掉方法上的 @TenantIgnore 重启,发同一个请求,对比 SQL 日志里的 tenant_id 条件。过滤器的无租户拦截见 pmforge-framework/pmforge-spring-boot-starter-biz-tenant/src/main/java/com/pmforge/framework/tenant/core/security/TenantSecurityWebFilter.java#L89。
  • 验收:有注解时返回跨租户总数(比无注解时多 1);无注解时 SQL 带 tenant_id = 1。若不带 tenant-id,即使有方法注解也会被 Web 过滤器拦成 code=400,提示租户标识未传递。
  • 延伸:把注解加到 DO 类上,验证它影响的是整张表而不是单个方法。

练习 5:写一个数据权限规则 ​

  • 目标:给练习 3 的 infra_training_note 加一条“只看本部门”的规则。
  • 前置:数据权限、部门卡
  • 步骤:
    1. 在 infra_training_note 插两条记录,dept_id 分别为 103、104;当前 admin 的部门是 103。
    2. 在 pmforge-module-system/src/main/java/com/pmforge/module/system/framework/datapermission/rule/TrainingNoteDataPermissionRule.java 新建 @Component 类实现 DataPermissionRule:getTableNames() 返回 infra_training_note,getExpression() 先判断 SecurityFrameworkUtils.getLoginUserDeptId() 为空则返回 null,否则用 MyBatisUtils.buildColumn(tableName, tableAlias, "dept_id") 构造 EqualsTo;两个方法签名见 pmforge-framework/pmforge-spring-boot-starter-biz-data-permission/src/main/java/com/pmforge/framework/datapermission/core/rule/DataPermissionRule.java#L25,现有部门列定制样例见 pmforge-module-system/src/main/java/com/pmforge/module/system/framework/datapermission/config/DataPermissionConfiguration.java#L21。
    3. 重启后调 GET /admin-api/infra/training-note/page?pageNo=1&pageSize=10,并打开 SQL 日志。
  • 验收:只返回 dept_id=103 的记录;SQL 里出现 dept_id = 103,104 的记录不出现。
  • 延伸:改成 dept_id IN (...),对比 DeptDataPermissionRule 的五种范围实现。

练习 6:用 @ApiAccessLog 观察访问日志落库 ​

  • 目标:让一次接口调用在 infra_api_access_log 留下可查的记录。
  • 前置:Web 过滤器与统一响应、访问日志卡
  • 步骤:
    1. 把 pmforge-server/src/main/resources/application-local.yaml#L246 的 Pmforge.access-log.enable 改为 true。
    2. 在练习 2 的 get-by-username 方法上加 @ApiAccessLog(operateType = OperateTypeEnum.GET)(补 import)。
    3. 重启后调用该接口,再查 SELECT * FROM infra_api_access_log ORDER BY id DESC LIMIT 1。
  • 验收:表里新增一行,request_url 是 /admin-api/system/user/get-by-username,operate_type=1,result_code=0。
  • 延伸:把 responseEnable 设为 true,观察日志里多出的响应体字段。

练习 7:用 @Idempotent 与限流注解 ​

  • 目标:分别观察重复请求 900 与限流 429。
  • 前置:保护 starter、鉴权与权限点
  • 步骤:
    1. 在用户 Controller 加两个测试方法:ping-idem 加 @Idempotent(timeout = 30),ping-rate 加 @RateLimiter(count = 2, time = 60),都返回 success("pong");字段默认值见 pmforge-framework/pmforge-spring-boot-starter-protection/src/main/java/com/pmforge/framework/idempotent/core/annotation/Idempotent.java#L28 与 pmforge-framework/pmforge-spring-boot-starter-protection/src/main/java/com/pmforge/framework/ratelimiter/core/annotation/RateLimiter.java#L29。
    2. 重启后连续调用两次 GET /admin-api/system/user/ping-idem。
    3. 连续调用三次 GET /admin-api/system/user/ping-rate。
  • 验收:第二次 ping-idem 返回 code=900、msg=重复请求,请稍后重试;第三次 ping-rate 返回 code=429、msg=请求过于频繁,请稍后重试。
  • 延伸:把 keyResolver 换成用户级或 IP 级,比较两种 key 的隔离效果。

练习 8:发一条 Redis 消息 ​

  • 目标:走通 pub/sub 的“消息体 + 监听器 + 发送”三步。
  • 前置:消息与实时推送、starter-mq
  • 步骤:
    1. 在 pmforge-module-infra 新建 TrainingMessage extends AbstractRedisChannelMessage,加 String text 字段与构造器;频道名默认取类简名,基类见 pmforge-framework/pmforge-spring-boot-starter-mq/src/main/java/com/pmforge/framework/mq/redis/core/pubsub/AbstractRedisChannelMessage.java#L19。
    2. 新建 @Component TrainingMessageListener extends AbstractRedisChannelMessageListener<TrainingMessage>,在 onMessage 里打日志;抽象方法见 pmforge-framework/pmforge-spring-boot-starter-mq/src/main/java/com/pmforge/framework/mq/redis/core/pubsub/AbstractRedisChannelMessageListener.java#L71。
    3. 在一个临时接口里注入 RedisMQTemplate,调用 redisMQTemplate.send(new TrainingMessage("hello"));发送方法见 pmforge-framework/pmforge-spring-boot-starter-mq/src/main/java/com/pmforge/framework/mq/redis/core/RedisMQTemplate.java#L38。
    4. 重启后调用接口,看应用日志。
  • 验收:日志出现 [onMessage][收到 hello];Redis 频道名为 TrainingMessage。
  • 延伸:给 pub/sub 加 try-catch 后对比 stream 的 ack 与重试语义。

练习 9:写一个 Quartz JobHandler ​

  • 目标:新增任务类并让它被调度器执行一次。
  • 前置:定时任务与异步、Job 卡
  • 步骤:
    1. 删除 pmforge-server/src/main/resources/application-local.yaml#L10 的 Quartz 排除行,重启前先确认本地库可写。
    2. 新建 TrainingJob implements JobHandler,加 @Component("trainingJob"),在 execute 里打日志并返回 ok:<param>;接口方法见 pmforge-framework/pmforge-spring-boot-starter-job/src/main/java/com/pmforge/framework/quartz/core/handler/JobHandler.java#L17。
    3. 调 POST /admin-api/infra/job/create,body 含 name、handlerName:"trainingJob"、cronExpression:"0 0 3 * * ?"、retryCount:0、retryInterval:0。
    4. 调 PUT /admin-api/infra/job/trigger?id=<任务 id>,再看 infra_job_log。
  • 验收:应用日志出现 TrainingJob 的参数;infra_job_log 新增一行且 status 为成功。
  • 延伸:把 cron 改成每 30 秒一次,观察 infra_job_log 的增长与重试字段。

练习 10:用 ExcelUtils 导出一张表 ​

  • 目标:复用 ExcelUtils.write,把一个查询结果写成可打开的 xls。
  • 前置:starter-excel、数据访问约定
  • 步骤:
    1. 在用户 Controller 加 GET /export-by-nickname,权限 system:user:export,方法体先 userService.getUserListByNickname(nickname),再 ExcelUtils.write(response, "按昵称导出.xls", "用户", UserRespVO.class, BeanUtils.toBean(list, UserRespVO.class));工具签名见 pmforge-framework/pmforge-spring-boot-starter-excel/src/main/java/com/pmforge/framework/excel/core/util/ExcelUtils.java#L33,现成样例见 pmforge-module-infra/src/main/java/com/pmforge/module/infra/controller/admin/demo/demo01/Demo01ContactController.java#L98。
    2. 重新打包并重启,调 GET /admin-api/system/user/export-by-nickname?nickname=admin。
    3. 用 Excel 或 WPS 打开下载文件。
  • 验收:响应头含 Content-Disposition,文件能被打开,表头是 UserRespVO 上的 @ExcelProperty 文本,行数与查询结果一致。
  • 延伸:把 UserRespVO 的一个字段换成本地化字典 converter,再导出对比。

练习 11:用 --check 制造并发现代码漂移 ​

  • 目标:亲眼看到“代码改了、生成物没更新”时校验如何失败。
  • 前置:如何使用本知识库、system API 页
  • 步骤:
    1. 在 UserController 临时加一个 @GetMapping("/drift-check") 方法,不运行 docs:gen;可照抄 pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L150 的写法。
    2. 在仓库根执行 node script/docs/scan-knowledge.mjs --check。
    3. 执行 npm run docs:gen,再跑一次 node script/docs/scan-knowledge.mjs --check。
  • 验收:第一次打印 生成物已过期,请运行 npm run docs:gen: 并列出 docs/code/api/system.md,退出码 1;第二次打印 生成物一致性校验通过。,退出码 0。
  • 延伸:改一个 @PreAuthorize 权限点再跑 --check,观察 docs/code/api/system.md 与权限点统计一起变化。

练习 12:给知识库新增一张功能卡 ​

  • 目标:只改数据源,让 docs:gen 生成新卡片和索引行。
  • 前置:功能卡模板、卡片索引
  • 步骤:
    1. 在 script/docs/cards.data.mjs#L10 的 CARDS 数组末尾(#L574 前)追加一个对象,至少写 id、title、module、controllers、value、roles、scenarios、tables、mechanisms、pitfalls。
    2. id 用 SYS-USER-03,controllers 写成 ['UserController'],tables 写成 ['system_users']。
    3. 执行 npm run docs:gen,再打开 docs/cards/SYS-USER-03.md 与 docs/cards/index.md。
  • 验收:新卡片文件带 generated: true 的 front-matter,索引表从 40 行变成 41 行;node script/docs/scan-knowledge.mjs --check 通过。
  • 延伸:给卡片补 prd 与 related,观察生成的“需求原件”和“相关卡片”链接。