03-01-Java项目结构与请求流程

0 阅读4分钟

学完本节,应能在不修改代码的情况下解释:一个 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/mapperMyBatis SQL 与字段映射
src/test/java/com/example/ticketJUnit 测试,不混进正式源码
src/test/resources/application-test.properties测试账号配置
scriptsPowerShell 手工接口验证
sql/01-schema.sql空练习库的两张表,含字段备注
target构建产生的结果;里面的旧报告不是当前代码的通过证明

曾经出现 org.junit.jupiter.api 不存在,是 TicketServiceTest.java 放进 src/main/java 引起的。测试依赖的 scope 是 test,正式编译不加载它。解决方法是把测试放到 src/test/java 对应包目录,而不是把所有测试依赖改成正式依赖。

2. 沿创建请求读六个文件

按以下次序打开源码,每次只回答一个问题。

  1. TicketApiApplication:main 方法启动 Spring。它是程序入口,不是处理每次工单的地方。
  2. CreateTicketRequest:接收 title 和 description。record 自动提供 title()、description() 等访问方法。
  3. TicketController:@PostMapping 接收 POST /api/tickets,@RequestBody 读取 JSON,@Valid 触发字段校验。
  4. TicketService:取得登录用户、检查标题、组装 TicketRow、调用 Mapper、转成响应。
  5. TicketMapper 与 mapper/TicketMapper.xml:接口方法对应 SQL,insert 把行写入 MySQL。
  6. 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。

更多请关注我的微信公众号,感谢!

微信图片_20260427132414_18_737.jpg