学完本节,应能在不修改代码的情况下解释:一个 JSON 如何变成数据库的一行,再变成 HTTP 响应。操作地点是 IDE,暂时不用 DBeaver,也不用运行构建。
1. 从目录认识项目
项目根目录是 C:\xixl-study\java-labs\ticket-api。
| 相对根目录的路径 | 负责什么 |
|---|---|
| pom.xml | 声明 JDK、依赖与 Maven 插件 |
| src/main/java/com/example/ticket | 正式运行的 Java 类 |
| src/main/resources/application.properties | 启动配置,引用环境变量 |
| src/main/resources/mapper | MyBatis SQL 与字段映射 |
| src/test/java/com/example/ticket | JUnit 测试,不混进正式源码 |
| src/test/resources/application-test.properties | 测试账号配置 |
| scripts | PowerShell 手工接口验证 |
| sql/01-schema.sql | 空练习库的两张表,含字段备注 |
| target | 构建产生的结果;里面的旧报告不是当前代码的通过证明 |
曾经出现 org.junit.jupiter.api 不存在,是 TicketServiceTest.java 放进 src/main/java 引起的。测试依赖的 scope 是 test,正式编译不加载它。解决方法是把测试放到 src/test/java 对应包目录,而不是把所有测试依赖改成正式依赖。
2. 沿创建请求读六个文件
按以下次序打开源码,每次只回答一个问题。
- TicketApiApplication:main 方法启动 Spring。它是程序入口,不是处理每次工单的地方。
- CreateTicketRequest:接收 title 和 description。record 自动提供 title()、description() 等访问方法。
- TicketController:@PostMapping 接收 POST /api/tickets,@RequestBody 读取 JSON,@Valid 触发字段校验。
- TicketService:取得登录用户、检查标题、组装 TicketRow、调用 Mapper、转成响应。
- TicketMapper 与 mapper/TicketMapper.xml:接口方法对应 SQL,insert 把行写入 MySQL。
- TicketResponse:控制返回给客户端的字段;Controller 返回 201 和 Location 响应头。
HTTP JSON → 安全过滤器 → Controller → Service → Mapper → MySQL
HTTP JSON ← TicketResponse ← Service ← 已回填编号的 TicketRow
安全过滤器会先验证身份和 CSRF。未通过时,请求不会走到 Controller,因此调试时“断点没有进入”不一定是 URL 写错。
3. 读懂最常见的 Java 写法
private final TicketMapper mapper;
public TicketService(TicketMapper mapper, TicketEventMapper eventMapper,
CurrentUser currentUser) {
this.mapper = mapper;
this.eventMapper = eventMapper;
this.currentUser = currentUser;
}
private 表示外部不能直接访问这个字段。构造器接收依赖,this.mapper 指当前对象字段,右边 mapper 指参数。Spring 创建 Service 时把 Mapper 传进来,这叫构造器注入;测试也能直接传入替身,方便隔离数据库。
final 字段表示赋值后不能重新指向另一个对象,不表示对象内部内容永远不变。final 方法表示子类不能重写该方法;final 类不能被继承。三种用法需要分开理解。
class 是普通类;interface 描述一组方法约定。TicketMapper 是接口,MyBatis 在运行时提供实现。record 适合表达请求和响应这样的数据载体;TicketRow 使用可写字段,是为了让 MyBatis 回填查询结果和数据库生成的 id。
long 不能为 null;Long 可以为 null。未接单时 assigneeId 为 null,表示还没有处理人。不能把 null 直接拆箱到 long。字符串比较不要用 ==;源码用 equals 比较状态内容。
Optional 表达“可能没有结果”。Controller 的 orElseThrow 把空结果转成项目定义的 404 异常。不要看到 Optional 就以为数据库会存 Optional。
4. 注解分别在哪一层起作用
| 注解 | 本项目用途 |
|---|---|
| @RestController | 将方法返回的数据写入 HTTP 响应 |
| @Service | 标记业务对象,由 Spring 管理 |
| @Mapper | 让 MyBatis 为数据访问接口提供实现 |
| @Valid、@NotBlank、@Size | 检查输入字段 |
| @Transactional | 为业务方法设置事务边界 |
| @RestControllerAdvice、@ExceptionHandler | 把异常转换成统一错误响应 |
| @Test | 标记测试方法,只放测试目录 |
注解不是“写上就万事大吉”。事务必须通过 Spring 管理的调用生效;权限要看配置与业务过滤;校验要看是否在入口触发。后面模块会分别验证。
5. 从内存版走到数据库版
课程 02 使用 Map 保存工单,AtomicLong 生成编号。AtomicLong 让同一个 Java 进程里的加一操作具备原子性,不会把数据保存到硬盘,也不能替代多个进程共享的数据库主键。
当前版本通过 MySQL AUTO_INCREMENT 生成 id,数据放进 tickets,因此不再依赖 AtomicLong。自增编号有空洞正常:测试回滚或失败插入都可能消耗编号,不要用“编号连续”作为业务正确性的判断。
课堂练习
不用运行程序,回答:给描述增加校验要看哪个文件?修改数据库列名要看哪个文件?修改取消规则要看哪个文件?
参考答案:输入字段看 CreateTicketRequest;列名映射看 TicketMapper.xml 与建表结构;取消规则看 TicketService.cancel 和 cancelOpenTicket 的 SQL,必要时同时修改测试。不能只改 Controller 返回文字。
下一节:[[03-02-MySQL表结构与SQL练习]]。来源:上述源码与现有课程 02、03。
更多请关注我的微信公众号,感谢!