Getting started

Local development

Common commands, directory tour, configuration discipline and troubleshooting.

This page answers three questions: which commands to type, where the code lives, and where to look first when something breaks.

Common commands

Command	What it does
`./gradlew bootRun`	Starts the app (Liquibase creates tables and seeds data)
`./gradlew build`	Compile + tests + architecture guards + contract consistency, all in one run
`./gradlew test`	Runs tests only
`./gradlew generateModule -Pname=demo`	Skeleton generator: module directories, migration script, test skeleton
`./gradlew bootJar`	Builds the runnable jar (`build/libs/`)

Note: a single ./gradlew build already runs compilation, tests, architecture guards, contract consistency and the formatting check. You do not run them separately.

Directory tour

minimao/
├── src/main/java/cn/minimao/
│   ├── app/<module>/{controller,service,dto,vo,convert}
│   ├── domain/handler/<module>/{cmd}
│   ├── infra/<module>/{model,mapper,repository,query}
│   ├── data/        # query and write foundation
│   ├── common/      # context, threads, exceptions
│   └── config/      # framework wiring
├── src/main/resources/
│   ├── db/changelog/   # Liquibase migrations (the only way to create tables)
│   ├── mapper/         # hand-written SQL
│   └── i18n/           # error messages in three languages
└── src/test/java/cn/minimao/{arch,behavior,support}

Configuration discipline

A new config key must be registered in both application.yml and .env.example; missing either fails the build.
Real credentials, intranet addresses and license keys never enter the repository; use <REQUIRED> as the placeholder.
Secrets are always injected as environment variables; .env is not versioned.

Debugging and logs

Every response body carries a traceId; front-end and back-end debugging use it as the single clue.
[] in the log means the line is not inside any request (startup, non-HTTP entry point), not that the chain was lost.
Access logging has exactly one print site, and phone numbers and password fields are masked by default.

Troubleshooting

Symptom	Look here first
Port already in use	change `server.port` or stop the process; do not change framework defaults
Migration failure at startup	check whether someone edited an already executed changeset in `db/changelog`
Pagination plugin unavailable	`mybatis-plus-jsqlparser` is missing (split out since 3.5.9)
"System busy" instead of a permission error	the error-code mapping is incomplete; no permission must return the fixed permission code
Empty traceId	confirm it is a non-HTTP entry point (scheduled task, message consumption, startup)

← Getting started in 5 minutes Deployment →

Last updated 2026-10-09Edit this page →