AKM Spring Boot 3 Development
A comprehensive coding standard for building enterprise-grade Spring Boot 3 applications with multi-tenant architecture, MyBatis persistence, Redis caching, and modern Jakarta EE 9+ standards.
Project Overview
This skill guides development of a Spring Boot 3 enterprise backend management system with:
Multi-tenant architectureMultiple database support (MySQL, PostgreSQL, DaMeng)Redis caching with local fallbackMinio file storageCustom permission control systemAPI documentation via SpringDoc OpenAPITechnology Stack
**Framework**: Spring Boot 3.5.7 (Spring 6.2.12)**Java**: Java 17 (use Java 17 features, NOT Java 8)**Web**: Spring MVC + Jakarta EE 9+**Persistence**: MyBatis 3.0.5 + HikariCP**Databases**: MySQL / PostgreSQL / DaMeng**Cache**: Redis (Lettuce) + Local cache**Storage**: Minio**Documentation**: SpringDoc OpenAPI (NOT Knife4j)**Utilities**: Hutool, Lombok, EasyExcel**Security**: Jasypt config encryption, custom auth**Other**: Magic APIInstructions
1. Response Language
**Always respond in Chinese** to users2. Project Structure
Follow this layered architecture strictly:
```
com.akm.springboot3/
├── core/ # Core module (config, utils, common components)
│ ├── annotation/ # Custom annotations
│ ├── config/ # Configuration classes
│ ├── constant/ # Constants
│ ├── domain/ # Common domain objects
│ ├── exception/ # Global exception handling
│ └── utils/ # Utility classes
├── web/ # Web layer
│ ├── biz/ # Business modules
│ │ ├── api/ # Controllers (API endpoints)
│ │ ├── domain/ # DTOs/VOs
│ │ ├── entity/ # Entities (database tables)
│ │ ├── mapper/ # MyBatis Mapper interfaces
│ │ └── service/ # Business logic layer
│ └── sys/ # System modules (users, roles, permissions)
└── file/ # File handling module
```
3. Naming Conventions
#### API Path Patterns
**Query endpoints**: `/xxx/view/{method}`**Operation endpoints**: `/xxx/op/{method}` (create, edit, delete)**Open endpoints**: `/xxx/open/{method}` (no auth required)**Public endpoints**: `/xxx/public/{method}` (login verification only)#### Class Naming
**Controller**: `XxxApi` (use `Api` suffix, NOT `Controller`)**Service**: `XxxService` + `XxxServiceImpl`**Mapper**: `XxxMapper`**Entity**: `BizXxx` / `SysXxx` (with business prefix)**DTO/VO**: Specific business names like `MessageQuery`, `AppCheckUpdate`#### Cache Key Standards
Define all keys in `RedisKeys` constant classUse `CacheUtils.prefixKey()` to add project prefixNever hardcode cache keys4. Custom Annotations
Use these project-specific annotations:
`@ApiFreqLimit`: API rate limiting`@CheckCsrfToken`: CSRF token validation`@IgnoreResultHandler`: Skip unified response wrapping`@IgnoreSysLog`: Skip system log recording5. API Documentation
Use Swagger annotations:
`@Tag`: Controller-level description`@Operation`: Method-level description`@Parameter`: Parameter descriptionLegacy compatibility: `@ApiModel`, `@ApiModelProperty`6. Configuration Management
#### Sensitive Data Encryption
Encrypt database passwords, Redis passwords with JasyptFormat: `ENC(encrypted_string)`Config key: `jasypt.encryptor.password`#### Configuration Files
`application.yaml`: Main config`application-dev.yaml`: Development environmentUse `@ConfigurationProperties` with `akm.*` prefix7. Database Layer (MyBatis)
#### Mapper Files
Place XML files in `resources/mapper/` directoryUse `#{param}` to prevent SQL injectionPagination: `PageHelper.startPage(page, size)`SQL logging: `akm.mybatis.print-sql: true`#### Entity Classes
Use Lombok: `@Getter`, `@Setter`, `@ToString`Date type: `java.util.Date` (NOT `java.time`)Use `@JsonFormat` for date formatting8. Caching Strategy
#### Cache Type Configuration
```yaml
akm:
cacheType: redis # Use 'redis' in production, 'local' for dev
```
#### Cache Utility Classes
`CacheUtils`: Generic cache operations (Object type)`StringCacheUtils`: String-specific cache operationsUse `CacheUtils.cacheAndGet()` with mutex locks to prevent cache breakdown9. Exception Handling
Business exceptions: `throw new BusinessException(CodeMsg.XXX)`Global handler: `GlobalExceptionHandler`Assertion utilities: `AssertUtils.notNull()`, `AssertUtils.isTrue()`10. Security Practices
#### Parameter Validation
Sensitive word filtering: Configure `akm.sensitiveWord`HTML escaping: Auto-handled (configurable exclusion paths)Signature validation: `akm.enabledSign: true`Encryption: `akm.enabledEncrypt: true`#### Permission Control
Enable: `akm.enabledAuth: true`Open endpoints: Paths containing `/open/`Public endpoints: Paths containing `/public/`11. Logging Standards
Use SLF4J: `Logger log = LoggerFactory.getLogger(XXX.class)`Log levels: ERROR > WARN > INFO > DEBUGLog file: `logs/spring.log`12. Spring Boot 3 Migration Points
#### Jakarta EE (NOT JavaEE)
✅ Use `jakarta.servlet.*`❌ Do NOT use `javax.servlet.*`#### Configuration Prefix Changes
✅ Use `spring.data.redis.*`❌ Do NOT use `spring.redis.*`#### Java 17 Features
✅ Use Records, sealed classes, switch expressions✅ Use Text Blocks for multi-line strings❌ Avoid Java 8 Date API (project uses `java.util.Date`)#### Dependency Injection
Prefer constructor injectionAvoid `@Autowired` field injection13. Utility Libraries
#### Hutool
Strings: `StrUtil`Collections: `CollUtil`Dates: `DateUtil`JSON: `JSONUtil`Encryption: `SecureUtil`#### Custom Utils
`CacheUtils`: Cache operations`StringUtils`: Enhanced string utilities`EncryptUtils`: Encryption/decryption`IpUtils`: IP processing`SnowflakeUtils`: ID generation`SpringContextHolder`: Get Spring beans14. API Development Template
```java
@Tag(name = "示例管理")
@RestController
@RequestMapping("/biz/example")
public class ExampleApi {
private final ExampleService exampleService;
// Constructor injection
public ExampleApi(ExampleService exampleService) {
this.exampleService = exampleService;
}
@Operation(summary = "查询列表")
@GetMapping("/view/list")
public PageResult<Example> list(ExampleQuery query) {
return exampleService.queryList(query);
}
@Operation(summary = "新增")
@PostMapping("/op/add")
public void add(@RequestBody Example example) {
exampleService.add(example);
}
}
```
15. Development Best Practices
#### Code Simplicity
Leverage Spring Boot auto-configuration where possibleRemove unnecessary Jackson configurations (Spring Boot 3 has sensible defaults)Use Lombok to reduce boilerplate code#### Performance Optimization
Cache hot data in RedisUse HikariCP connection pool (default)Use async tasks: `@Async` (configured in `AsyncConfig`)#### Testing Standards
Unit tests in `src/test/java`Integration tests: `@SpringBootTest`Mock external dependencies#### Git Commit Format
Pattern: `[type] brief description`Types: feat/fix/docs/refactor/test/choreExamples
Example 1: Create a Business API
**User Request**: "Create a product management API with list and add operations"
**Steps**:
1. Create entity `BizProduct` in `web/biz/entity/`
2. Create DTO `ProductQuery` in `web/biz/domain/`
3. Create `ProductMapper` interface and XML in `web/biz/mapper/`
4. Create `ProductService` + `ProductServiceImpl` in `web/biz/service/`
5. Create `ProductApi` controller in `web/biz/api/` using template above
6. Use `/biz/product/view/list` and `/biz/product/op/add` paths
Example 2: Add Redis Caching
**User Request**: "Cache product list with 5-minute expiration"
**Steps**:
1. Define cache key in `RedisKeys`: `public static final String PRODUCT_LIST = "product:list";`
2. In service method:
```java
String cacheKey = CacheUtils.prefixKey(RedisKeys.PRODUCT_LIST);
return CacheUtils.cacheAndGet(cacheKey, 5 * 60, () -> {
return productMapper.selectList(query);
});
```
Example 3: Add Custom Annotation
**User Request**: "Add rate limiting to login API"
**Steps**:
1. Add annotation to method:
```java
@ApiFreqLimit(seconds = 60, maxCount = 5)
@PostMapping("/op/login")
public LoginResult login(@RequestBody LoginRequest request) {
// ...
}
```
Important Notes
**Always respond in Chinese** to usersUse **Jakarta EE** (`jakarta.*`), not JavaEE (`javax.*`)Use **Java 17 features**, avoid Java 8 patternsFollow **API path conventions** strictly (`/view/`, `/op/`, `/open/`, `/public/`)Controller classes must end with **`Api`**, not `Controller`Use **constructor injection**, not field `@Autowired`Encrypt sensitive configs with **Jasypt**Use `java.util.Date`, NOT `java.time` classesDefine cache keys in `RedisKeys` constant classUse **SpringDoc OpenAPI**, NOT Knife4jTroubleshooting
**Maven Build Issues**:
1. Switch to Java 17: `java21` (if using version manager)
2. Clean build: `mvn clean install`
**Startup Failures**:
1. Check logs: `logs/spring.log`
2. Verify database connection
3. Verify Redis connection
4. Check port 33000 availability
**Deployment**:
Build: `mvn clean package -DskipTests`Run: `java -jar target/akm-springboot3-0.0.1-SNAPSHOT.jar`Profile: `--spring.profiles.active=prod`