⌕EN源码
快速开始

本地开发

常用命令、目录导览、配置纪律与故障排查。

这一页回答三件事：命令怎么敲、代码在哪、出问题先看哪里。

常用命令

命令作用
./gradlew bootRun启动应用（Liquibase 自动建表 + 种子数据）
./gradlew build编译 + 测试 + 架构守护 + 契约一致性，一次跑完
./gradlew test只跑测试
./gradlew generateModule -Pname=demo骨架生成器：产出模块目录、迁移脚本与测试骨架
./gradlew bootJar打出可运行的 jar（build/libs/）

说明：一次 ./gradlew build 会同时跑完编译、测试、架构守护、契约一致性与格式化校验——不需要分别执行。

目录导览

minimao/
├── src/main/java/cn/minimao/
│   ├── app/<module>/{controller,service,dto,vo,convert}
│   ├── domain/handler/<module>/{cmd}
│   ├── infra/<module>/{model,mapper,repository,query}
│   ├── data/        # 查询与写入底座
│   ├── common/      # 上下文、线程、异常
│   └── config/      # 框架装配
├── src/main/resources/
│   ├── db/changelog/   # Liquibase 迁移脚本（唯一建表入口）
│   ├── mapper/         # 手写 SQL
│   └── i18n/           # 三语错误文案
└── src/test/java/cn/minimao/{arch,behavior,support}

配置纪律

  • 新增配置项必须在 application.yml 与 .env.example 两处都登记，缺一处构建失败。
  • 真实凭据、内网地址、授权码一律不入库；占位符用 <REQUIRED>。
  • 密钥一律环境变量注入，.env 不进版本库。

调试与日志

  • 每个响应体都带 traceId，前端与后端排查以此为唯一线索。
  • 日志里 [] 表示这一行不在任何请求链路内（启动期、非 HTTP 入口），不是链路丢失。
  • 接口访问日志只有一个打印点，且手机号、密码类字段默认脱敏。

故障排查

现象先看这里
端口被占用改 server.port 或停掉占用进程；不要改框架默认行为
启动报迁移失败看 db/changelog 是否有人修改了已执行的 changeset
分页插件不可用是否漏了 mybatis-plus-jsqlparser（3.5.9 起拆包）
无权限时返回「系统繁忙」错误码映射是否补齐；无权限应返回固定权限错误码，不该落到兜底异常
traceId 为空确认是否非 HTTP 入口（定时任务 / 消息消费 / 启动期）
← 5 分钟上手部署 →
最后更新 2026-10-09编辑此页 →
5 分钟跑起来