AGENTS.md – Spring Boot Backend Development-北京尧图网络

AGENTS.md – Spring Boot Backend Development进行后端功能开发时候请遵守以下规范严禁自由发挥1. Project OverviewFramework: Spring Boot 3.x (with Java 17)Build Tool: MavenPersistence: Spring Data JPA (Hibernate) MySQLConnection Pool: Druid (Alibaba) – configured viaapplication.ymlAPI Style: RESTful JSON over HTTPSecurity: Spring Security with JWT (or OAuth2)Documentation: OpenAPI 3 (springdoc-openapi)Testing: JUnit 5, Mockito, Spring Boot Test, Testcontainers (MySQL)Logging: SLF4J LogbackCaching: Spring Cache (optional)2. Project Structure (Maven layout)src/ ├── main/ │ ├── java/com/example/app/ │ │ ├── AppApplication.java # Main class │ │ ├── config/ # Configuration classes (including DruidConfig) │ │ ├── controller/ # REST controllers (e.g., UserController) │ │ ├── service/ # Business logic interfaces implementations │ │ ├── repository/ # Spring Data JPA repositories │ │ ├── model/entity/ # JPA entities (e.g., User, Order) │ │ ├── model/dto/ # Data Transfer Objects (request/response) │ │ ├── mapper/ # MapStruct or manual mappers │ │ ├── exception/ # Custom exceptions and global handlers │ │ ├── security/ # Security config, filters, JWT utils │ │ ├── util/ # Utility classes │ │ └── validation/ # Custom validators │ └── resources/ │ ├── application.yml # Main configuration (profile: dev) │ ├── application-prod.yml │ ├── db/migration/ # Flyway/Liquibase scripts (if used) │ └── static/ # (if any) └── test/ ├── java/com/example/app/ │ ├── controller/ # Web layer tests (WebMvcTest) │ ├── service/ # Unit tests with Mockito │ └── repository/ # Data layer tests (DataJpaTest) └── resources/ └── application-test.yml3. Coding Conventions3.1. NamingClasses: PascalCase, singular nouns (e.g.,UserService,OrderRepository).Interfaces: UseIprefix?No– standard Java naming:UserService(interface),UserServiceImpl(implementation).Methods: camelCase, verbs (e.g.,findById,createOrder).Constants: UPPER_SNAKE_CASE.Packages: all lowercase, dot-separated.3.2. Annotations PatternsUseLombokto reduce boilerplate:Data,Builder,AllArgsConstructor,NoArgsConstructor,Slf4j.Preferconstructor injectionover field injection for better testability.UseTransactionalat the service layer for database operations.For DTOs, useValidwith Jakarta Bean Validation (NotNull,Size, etc.).3.3. REST API DesignUse plural nouns for resources:/api/users,/api/orders.HTTP methods: GET, POST, PUT, PATCH, DELETE.Return appropriate status codes (200, 201, 400, 404, 422, 500).Always useResponseEntityto wrap responses.3.4. Exception HandlingCreate a globalControllerAdvicethat handles:MethodArgumentNotValidException→ 400 Bad RequestEntityNotFoundException(custom) → 404 Not FoundAccessDeniedException→ 403 ForbiddenRuntimeException→ 500 Internal Server ErrorReturn a consistent error payload:{ timestamp, status, error, message, path }.3.5. LoggingUseSlf4jand log at appropriate levels:INFOfor significant events (startup, successful operations).DEBUGfor detailed flow (e.g., SQL parameters, method entry/exit).WARNfor recoverable issues.ERRORfor exceptions caught by global handler.Never log sensitive data (passwords, tokens).4. Development Workflow4.1. Setting Up Local EnvironmentInstall JDK 17, Maven, Docker (optional for MySQL).Create a MySQL database (e.g.,app_db).Adjustapplication.ymlspring.datasourcesettings (see Section 6).Run database migrations (Flyway/Liquibase) on startup (enabled by default).4.2. Adding a New FeatureDefine the entity– inmodel/entity/with JPA annotations.Create repository– extendJpaRepositoryT, ID.Create DTOs– request and response objects inmodel/dto/.Write service interface and implementation– business logic, using repository.Create controller– map endpoints, useValidon request bodies.Add validation annotationson DTO fields.Write unit testsfor service and repository layers.Update OpenAPI documentation(if usingspringdoc).4.3. Database MigrationsUse Flyway (or Liquibase) scripts indb/migration/.Version files:V1__initial_schema.sql,V2__add_created_at.sql.Ensure SQL syntax is MySQL-compatible.Never modify existing scripts; create new versions.4.4. Testing StrategyUnit Tests– for service classes with mocked repositories.Integration Tests– withSpringBootTestand Testcontainers for MySQL.Web Slice Tests–WebMvcTestfor controller layer.Data Slice Tests–DataJpaTestfor repository queries.Aim for 80% coverage on critical business logic.5. Security GuidelinesUseSpring Securitywith JWT.Secure endpoints withPreAuthorizeorSecuredannotations.Store passwords usingBCryptPasswordEncoder.Never expose sensitive fields in DTOs (e.g., password).Validate JWT token via a filter (once-per-request).6. Configuration ManagementUseapplication.ymlfor default settings.Environment-specific overrides:application-dev.yml,application-prod.yml.UseConfigurationPropertiesfor grouping external config (e.g.,app.jwt.secret).Druid Connection Pool ConfigurationAdd the following toapplication.yml:spring:datasource:driver-class-name:com.mysql.cj.jdbc.Driverurl:jdbc:mysql://localhost:3306/app_db?useSSLfalseserverTimezoneUTCallowPublicKeyRetrievaltrueusername:rootpassword:yourpasswordtype:com.alibaba.druid.pool.DruidDataSourcedruid:# Initial connection pool sizeinitial-size:5# Minimum idle connectionsmin-idle:5# Maximum active connectionsmax-active:20# Connection timeout (ms)max-wait:60000# Time between eviction checks (ms)time-between-eviction-runs-millis:60000# Minimum evictable idle time (ms)min-evictable-idle-time-millis:300000# Validation queryvalidation-query:SELECT 1# Test while idletest-while-idle:true# Test on borrow (false recommended)test-on-borrow:false# Test on return (false recommended)test-on-return:false# Enable PoolPreparedStatementspool-prepared-statements:truemax-pool-prepared-statement-per-connection-size:20# Filter configuration (optional)filters:stat,wall# WebStatFilter (for monitoring)web-stat-filter:enabled:trueurl-pattern:/*exclusions:*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid/*# StatViewServlet (for Druid console)stat-view-servlet:enabled:trueurl-pattern:/druid/*login-username:adminlogin-password:admin123reset-enable:falseNote: You may also configure Druid via a separateConfigurationclass if you need more advanced settings.7. Build Run CommandsBuild:mvn clean packageRun:mvn spring-boot:runTests:mvn test(with profiles)Docker:docker build -t app .(if Dockerfile exists)8. Code QualityUseSonarQubeorSpotBugsfor static analysis.Format code withGoogle Java Style(or usespotlessplugin).AvoidSystem.out.println; use logging.9. AI Agent Specific InstructionsWhen generating or suggesting code, please adhere to the following:Generate complete code blockswith proper imports and package declarations.Always include exception handlingfor repository/service calls.UseAutowiredonly when constructor injection is impractical; prefer constructor injection.When writing REST endpoints, provide OpenAPI annotations (Operation,ApiResponse) for automatic docs.For new DTOs, includeSchemaannotations for OpenAPI.Write test classesfor every new service/controller, using given-when-then style.PreferStreamAPIfor collection processing.UseOptionalfor nullable return types (e.g., from repository find methods).Avoid usingnull; useOptionalor throw appropriate exception.For pagination, use Spring’sPageableand returnPageT.When interacting with external APIs, useRestClientorWebClientwith timeout and retry.10. Useful Dependencies (Maven)Add the following to yourpom.xml:dependencies!-- Spring Boot Starters --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-data-jpa/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-security/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-validation/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-cache/artifactId/dependency!-- MySQL Driver --dependencygroupIdcom.mysql/groupIdartifactIdmysql-connector-j/artifactIdscoperuntime/scope/dependency!-- Druid Connection Pool --dependencygroupIdcom.alibaba/groupIdartifactIddruid-spring-boot-3-starter/artifactIdversion1.2.23/version/dependency!-- Database Migration (Flyway) --dependencygroupIdorg.flywaydb/groupIdartifactIdflyway-core/artifactId/dependencydependencygroupIdorg.flywaydb/groupIdartifactIdflyway-mysql/artifactId/dependency!-- OpenAPI / Swagger --dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.5.0/version/dependency!-- JWT --dependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-api/artifactIdversion0.12.5/version/dependencydependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-impl/artifactIdversion0.12.5/versionscoperuntime/scope/dependencydependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-jackson/artifactIdversion0.12.5/versionscoperuntime/scope/dependency!-- Lombok --dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdoptionaltrue/optional/dependency!-- Test --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependencydependencygroupIdorg.springframework.security/groupIdartifactIdspring-security-test/artifactIdscopetest/scope/dependencydependencygroupIdorg.testcontainers/groupIdartifactIdtestcontainers/artifactIdversion1.19.8/versionscopetest/scope/dependencydependencygroupIdorg.testcontainers/groupIdartifactIdmysql/artifactIdversion1.19.8/versionscopetest/scope/dependency/dependenciesVersion notes: Adjust versions as needed. Thedruid-spring-boot-3-starteris compatible with Spring Boot 3.x.11. Common Pitfalls to AvoidDo not expose internal entity objects directly in API responses (use DTOs).Avoid lazy loading exceptions; useTransactionalor fetch joins.Do not injectHttpServletRequestin service layer.Avoid tight coupling between packages; follow hexagonal/clean architecture if applicable.Do not ignoreValidon request body; always validate input.Ensure MySQL timezone and SSL settings match your environment.Druid filters (stat, wall) are optional but recommended for monitoring and SQL injection protection.12. Final NotesAlways run tests locally before pushing.For any major change, update theREADME.mdand AGENTS.md accordingly.Feel free to ask clarifying questions if requirements are ambiguous.最后再次说明进行后端功能开发时候请遵守以上规范严禁自由发挥

AGENTS.md – Spring Boot Backend Development

相关推荐

Unity自动滚动文本框实现：RectTransform动画与UGUI动态布局

智慧园区照明监控与能源管理系统方案

【梯级水电】混合式抽水蓄能+梯级水电+源网荷储研究（Matlab代码实现）

更多资讯

CivitAI 的 `dbRead`/`dbWrite` 双客户端路由：当服务层在运行时选择数据库客户端时，测试 mock 如何正确拆分

2026年硕博新生报到须知及新生入校相关注意事项汇总

查aigc免费网站靠谱吗？准确率98.54%的AI率报告带编号可核验，查重报告没有

aigc检测器哪个学校在用？中南大学、湘潭大学等高校AI率查重系统清单

Oracle 11g透明网关访问SQL Server：从安装配置到排错完整指南

STM32CubeMX生成IAR工程实战指南：配置、编译与常见坑

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？