主题
练习与自测
练习都可回滚,做完用 git checkout -- <路径> 还原(新增文件直接删除)。
练习 1:追一条新增用户链路
- 目标:从 Controller 追到 Mapper,说清每层做了什么。
- 前置:请求处理链路、用户新增卡
- 步骤:
- 在
pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L54看权限点,#L56看 Controller 只接收参数并转调 Service。 - 在
pmforge-module-system/src/main/java/com/pmforge/module/system/service/user/AdminUserServiceImpl.java#L99看租户账号数校验,#L114看userMapper.insert(user)。 - 在
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。 - 用
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 模块
- 步骤:
- 在
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)。 - 在菜单 100 下加按钮:
INSERT INTO system_menu (name, permission, type, sort, parent_id) VALUES ('按用户名查询','system:user:read',3,9,100);;type=3是按钮,非超管还要通过system_role_menu给角色授权。 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 模块
- 步骤:
- 在
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');- 调
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。 - 调
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。 - 执行 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”。
- 前置:多租户、租户卡
- 步骤:
- 直接插一个租户 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);。 - 在
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。 - 带
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。
- 直接插一个租户 2 的用户作对照:
- 验收:有注解时返回跨租户总数(比无注解时多 1);无注解时 SQL 带
tenant_id = 1。若不带tenant-id,即使有方法注解也会被 Web 过滤器拦成code=400,提示租户标识未传递。 - 延伸:把注解加到 DO 类上,验证它影响的是整张表而不是单个方法。
练习 5:写一个数据权限规则
- 目标:给练习 3 的
infra_training_note加一条“只看本部门”的规则。 - 前置:数据权限、部门卡
- 步骤:
- 在
infra_training_note插两条记录,dept_id分别为 103、104;当前 admin 的部门是 103。 - 在
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。 - 重启后调
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 过滤器与统一响应、访问日志卡
- 步骤:
- 把
pmforge-server/src/main/resources/application-local.yaml#L246的Pmforge.access-log.enable改为true。 - 在练习 2 的
get-by-username方法上加@ApiAccessLog(operateType = OperateTypeEnum.GET)(补 import)。 - 重启后调用该接口,再查
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、鉴权与权限点
- 步骤:
- 在用户 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。 - 重启后连续调用两次
GET /admin-api/system/user/ping-idem。 - 连续调用三次
GET /admin-api/system/user/ping-rate。
- 在用户 Controller 加两个测试方法:
- 验收:第二次
ping-idem返回code=900、msg=重复请求,请稍后重试;第三次ping-rate返回code=429、msg=请求过于频繁,请稍后重试。 - 延伸:把
keyResolver换成用户级或 IP 级,比较两种 key 的隔离效果。
练习 8:发一条 Redis 消息
- 目标:走通 pub/sub 的“消息体 + 监听器 + 发送”三步。
- 前置:消息与实时推送、starter-mq
- 步骤:
- 在
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。 - 新建
@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。 - 在一个临时接口里注入
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。 - 重启后调用接口,看应用日志。
- 在
- 验收:日志出现
[onMessage][收到 hello];Redis 频道名为TrainingMessage。 - 延伸:给 pub/sub 加 try-catch 后对比 stream 的 ack 与重试语义。
练习 9:写一个 Quartz JobHandler
- 目标:新增任务类并让它被调度器执行一次。
- 前置:定时任务与异步、Job 卡
- 步骤:
- 删除
pmforge-server/src/main/resources/application-local.yaml#L10的 Quartz 排除行,重启前先确认本地库可写。 - 新建
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。 - 调
POST /admin-api/infra/job/create,body 含name、handlerName:"trainingJob"、cronExpression:"0 0 3 * * ?"、retryCount:0、retryInterval:0。 - 调
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、数据访问约定
- 步骤:
- 在用户 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。 - 重新打包并重启,调
GET /admin-api/system/user/export-by-nickname?nickname=admin。 - 用 Excel 或 WPS 打开下载文件。
- 在用户 Controller 加
- 验收:响应头含
Content-Disposition,文件能被打开,表头是UserRespVO上的@ExcelProperty文本,行数与查询结果一致。 - 延伸:把
UserRespVO的一个字段换成本地化字典 converter,再导出对比。
练习 11:用 --check 制造并发现代码漂移
- 目标:亲眼看到“代码改了、生成物没更新”时校验如何失败。
- 前置:如何使用本知识库、system API 页
- 步骤:
- 在
UserController临时加一个@GetMapping("/drift-check")方法,不运行docs:gen;可照抄pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L150的写法。 - 在仓库根执行
node script/docs/scan-knowledge.mjs --check。 - 执行
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生成新卡片和索引行。 - 前置:功能卡模板、卡片索引
- 步骤:
- 在
script/docs/cards.data.mjs#L10的CARDS数组末尾(#L574前)追加一个对象,至少写id、title、module、controllers、value、roles、scenarios、tables、mechanisms、pitfalls。 id用SYS-USER-03,controllers写成['UserController'],tables写成['system_users']。- 执行
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,观察生成的“需求原件”和“相关卡片”链接。