kxs-boot/AGENTS.md

AGENTS.md - LXQ Spring Boot Development Guidelines

Project Overview

Java 21, Spring Boot 3.5.9, Maven multi-module project with MyBatis-Plus, Redis, RocketMQ, OAuth2.

Essential Commands

# Build & Run
mvn clean compile              # Compile
mvn clean package              # Package JAR
mvn spring-boot:run            # Run application
mvn clean install              # Install to local repo

# Testing
mvn test                       # Run all tests
mvn test -Dtest=ClassName      # Single test class
mvn test -Dtest=ClassName#methodName  # Single test method

# Code Quality
mvn spring-javaformat:apply    # Format code (MANDATORY before commits)
mvn validate                   # Check format during build

# Environment builds
mvn clean package -Pdev        # Development (default)
mvn clean package -Ptest       # Test environment
mvn clean package -Pprod       # Production

Code Style

• Formatter: Spring Java Format plugin (v0.0.39) - REQUIRED before commits
• Indentation: 4 spaces, no tabs
• Line endings: LF (Unix)
• Max line length: 120 chars
• No wildcard imports
• Line comments only (no block comments)

Naming Conventions

Element	Convention	Examples
Class/Interface	PascalCase	SysUserController, UserDTO
Method/Variable	camelCase	getUserById, saveUser()
Constant	UPPER_SNAKE_CASE	DEFAULT_PAGE_SIZE, COMMON_STATUS
Package	com.kxs.{module}.biz.{layer}	com.kxs.admin.biz.controller

Architecture Layers

com.kxs.{module}.biz.controller/   # REST endpoints
com.kxs.{module}.biz.service/       # Business logic
com.kxs.{module}.biz.mapper/        # Data access
com.kxs.{module}.biz.model/         # Entities
com.kxs.{module}.biz.domain.dto/    # Input DTOs
com.kxs.{module}.biz.domain.vo/     # Response VOs

Layer Patterns

• Controllers: @RestController, @AllArgsConstructor, return R<T>
• Services: Extend IService<Entity>, use @SysLog
• Mappers: Extend BaseMapper<Entity>
• DTOs: @Data, @Schema, extend Entity when appropriate
• VOs: @Data, @Schema for API responses

Database & ORM

@TableName("table_name")
@TableId(type = IdType.AUTO)
public class Entity { }  // del_flag for logical deletion

// Query with type-safe wrapper
Wrappers.<Entity>query().lambda()
    .eq(Entity::getField, value)
    .orderByDesc(Entity::getCreateTime);

• Dynamic Datasource: @DS("datasource_name")
• Joins: Use MyBatis-Plus-Join library

API Documentation (Knife4j/Swagger)

@Tag(description = "module", name = "description")        // Class
@Operation(summary = "action", description = "details")   // Method
@ParameterObject                                        // Query params
@Schema(description = "...")                            // Fields
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)  // Secured APIs

Security

@PreAuthorize("@pms.hasPermission('module_action')")  // Permission check
@Inner  // Internal API (bypass OAuth2)
SecurityUtils.getUser()  // Current user info

• Permission format: module_action (e.g., sys_user_add)

Error Handling

return R.ok(data);                    // Success
return R.failed("error message");     // Error
return R.failed(ErrorEnum);           // Error with enum

@Slf4j  // Logger
@RestControllerAdvice  // Global exception handler

Key Requirements

1. ALWAYS run mvn spring-javaformat:apply before commits
2. ALWAYS return R<T> from controllers
3. ALWAYS use @PreAuthorize for security
4. ALWAYS document APIs with Swagger annotations
5. FOLLOW Controller → Service → Mapper pattern
6. USE DTOs for input, VOs for output
7. USE @SysLog for business operations

Configuration

• Main config: kxs-admin/src/main/resources/application.yml
• Profiles: application-{dev|test|prod}.yml
• Server: Port 8080, context path /v1/admin