spring-boot-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Composition

组合使用

compose with
```
java-conventions
```
for all language-level Java rules (syntax, style, naming, visibility, interfaces/classes, methods/lambdas, streams/collections, exceptions, comments/JavaDoc)
compose with an architecture skill when architecture is specified or already present, such as
```
bce
```
,
```
sdd4j-bce
```
,
```
sdd4j-package-by-feature
```
, or
```
sdd4j-package-by-layer
```
when no architecture is specified, infer and preserve the existing project organization instead of introducing BCE, package-by-feature, or package-by-layer by default
this skill specializes only the Spring Boot server stack and does not restate language-level Java or architecture-level rules

所有Java语言层面的规则（语法、风格、命名、可见性、接口/类、方法/lambda、流/集合、异常、注释/JavaDoc）需与
```
java-conventions
```
技能组合使用
当指定了架构或项目已有架构时，与对应架构技能组合使用，例如
```
bce
```
、
```
sdd4j-bce
```
、
```
sdd4j-package-by-feature
```
或
```
sdd4j-package-by-layer
```
未指定架构时，推断并保留现有项目的组织方式，默认不引入BCE、按功能分包或按层分包的架构
本技能仅针对Spring Boot服务端技术栈做专项规范，不重复陈述Java语言层面或架构层面的规则

Dependencies

依赖管理

prefer dependencies in this order: Java SE, Spring Boot starters already present in the project, Spring ecosystem modules already used by the project
avoid adding dependencies for problems already solved by Spring Boot, Java SE, or the existing project stack
ask before changing Maven
```
pom.xml
```
, Gradle build files, dependency versions, Java version, Spring Boot version, or plugin configuration
do not introduce a second web stack; Spring MVC and WebFlux should not be mixed unless the existing project already does so deliberately

依赖优先级按以下顺序选择：Java SE、项目中已有的Spring Boot starters、项目已使用的Spring生态模块
对于Spring Boot、Java SE或现有项目技术栈已能解决的问题，避免新增依赖
修改Maven
```
pom.xml
```
、Gradle构建文件、依赖版本、Java版本、Spring Boot版本或插件配置前需先询问用户
不引入第二套Web技术栈；除非现有项目已刻意混用，否则不得同时使用Spring MVC和WebFlux

Architecture Fit

架构适配

treat Spring Boot as the application stack, not as the architecture
preserve the architecture already used by the project, including package-by-feature, package-by-layer, BCE, hexagonal, clean architecture, modular monolith, or a local project convention
do not rename packages, introduce architectural layers, or reorganize code solely because this skill is active
when adding new code, place it where equivalent Spring components already live
when no convention exists, choose the smallest clear structure for the requested change and avoid committing the project to a broad architecture prematurely
keep Spring framework annotations at application entry points, application services, configuration, adapters, and persistence integration points; avoid leaking Spring concerns into domain code unless the project already follows an active-record or Spring-centric model

将Spring Boot视为应用技术栈，而非架构
保留项目已使用的架构，包括按功能分包、按层分包、BCE、六边形架构、整洁架构、模块化单体或项目本地约定
不得仅因启用本技能就重命名包、引入架构层或重组代码
新增代码时，放置在已有同类Spring组件所在的位置
无现有约定时，为所需变更选择最小的清晰结构，避免过早让项目绑定到宽泛的架构
将Spring框架注解保留在应用入口、应用服务、配置、适配器和持久化集成点；除非项目已遵循活动记录或以Spring为中心的模式，否则避免将Spring相关逻辑泄漏到领域代码中

Web/API Entry Points

Web/API 入口层

place Spring MVC controllers, REST API DTO mapping, request/response models, scheduled entry points, messaging listeners, external API clients, health indicators, and protocol adapters according to the existing architecture
name REST controllers in plural after the resource they expose, e.g.
```
SpeakersController
```
rather than
```
SpeakerController
```
keep controllers coarse-grained and free of business logic; validate and translate HTTP input, then delegate to application services, handlers, or use cases
use
```
@RestController
```
for JSON HTTP APIs and
```
@Controller
```
only when rendering views or redirects is intentional
declare request mappings at class level where it clarifies the resource path
return
```
ResponseEntity<T>
```
when status, headers, or empty responses matter; return DTOs directly only for straightforward successful responses
put
```
@Transactional
```
on request-sized use case methods when the transaction boundary is intentionally tied to that entry point
avoid calling repositories directly from controllers except for trivial generated code explicitly requested by the user

根据现有架构放置Spring MVC控制器、REST API DTO映射、请求/响应模型、定时任务入口、消息监听器、外部API客户端、健康检查指示器和协议适配器
REST控制器以其暴露的资源的复数形式命名，例如
```
SpeakersController
```
而非
```
SpeakerController
```
保持控制器粗粒度，不包含业务逻辑；仅负责校验和转换HTTP输入，然后委托给应用服务、处理器或用例
JSON HTTP API使用
```
@RestController
```
，仅当需要渲染视图或重定向时才使用
```
@Controller
```
当能明确资源路径时，在类级别声明请求映射
当需要自定义状态码、响应头或空响应时返回
```
ResponseEntity<T>
```
；仅对于简单的成功响应直接返回DTO
当事务边界有意绑定到入口点时，在请求级别的用例方法上添加
```
@Transactional
```
除用户明确要求的简单生成代码外，避免在控制器中直接调用repository

Application Logic

应用逻辑层

implement procedural business logic and application use cases in the project's existing service/application/use-case location
use Spring stereotypes such as
```
@Service
```
or
```
@Component
```
for injectable application classes
keep application services independent of HTTP, servlet, controller, and JSON serialization details
let application methods express use cases in domain terms rather than transport terms
place
```
@Transactional
```
on application service/use-case methods when the transaction is intentionally scoped to reusable application logic
prefer constructor injection; avoid field injection

在项目现有的service/application/use-case目录中实现过程式业务逻辑和应用用例
对于可注入的应用类，使用
```
@Service
```
或
```
@Component
```
等Spring构造型注解
保持应用服务独立于HTTP、servlet、控制器和JSON序列化细节
应用方法应以领域术语而非传输术语来表达用例
当事务范围有意限定为可复用的应用逻辑时，在应用服务/用例方法上添加
```
@Transactional
```
优先使用构造器注入；避免字段注入

Domain And Data Model

领域与数据模型

maintain domain objects, data classes, JPA entities, value objects, enums, and domain behavior in the project's existing model/domain/entity location
entities maintain state and corresponding behavior
model stable value objects as records or enums when appropriate
direct references across independent modules, features, or components are allowed when they fit the existing architecture, but aim for maximal cohesion and minimal coupling
if a relation exists in the database, the entity model must carry a corresponding reference, id field, or association; the DB schema is the source of truth when it already exists
excessive cross-module references or shared configuration are refactoring signals; split, merge, or rebalance responsibilities to restore cohesion
keep JPA annotations out of DTOs and controller request/response types

在项目现有的model/domain/entity目录中维护领域对象、数据类、JPA实体、值对象、枚举和领域行为
实体维护状态及对应的行为
合适的情况下将稳定的值对象建模为record或枚举
跨独立模块、功能或组件的直接引用在符合现有架构时是允许的，但应追求高内聚低耦合
如果数据库中存在关联关系，实体模型必须包含对应的引用、ID字段或关联；当DB schema已存在时，以其为唯一事实来源
过多的跨模块引用或共享配置是需要重构的信号；应拆分、合并或重新平衡职责以恢复内聚性
不要在DTO和控制器请求/响应类型中添加JPA注解

Repositories And Persistence

仓库与持久化

place Spring Data repositories near the aggregate, feature, service, or persistence package that owns the persistent concept according to the existing architecture
repositories may live in application, domain, persistence, infrastructure, adapter, feature, or entity packages depending on the project convention; follow that convention consistently
do not expose Spring Data repositories directly as REST resources unless the project already uses Spring Data REST and the user explicitly wants that style
avoid leaking
```
Pageable
```
,
```
Page
```
,
```
Specification
```
, or persistence-specific types outside Spring-facing API/application code unless the existing API contract already exposes them
prefer explicit query methods or small custom queries over broad generic repository use in business logic

根据现有架构，将Spring Data仓库放置在所属持久化概念对应的聚合、功能、服务或持久化包附近
仓库可以位于application、domain、persistence、infrastructure、adapter、feature或entity包中，具体取决于项目约定；始终遵循该约定
除非项目已使用Spring Data REST且用户明确需要这种风格，否则不要将Spring Data仓库直接暴露为REST资源
避免在面向Spring的API/应用代码之外泄漏
```
Pageable
```
、
```
Page
```
、
```
Specification
```
或持久化特定类型，除非现有API契约已经暴露了这些类型
业务逻辑中优先使用明确的查询方法或小型自定义查询，而非宽泛的通用仓库

Exceptions And HTTP Errors

异常与HTTP错误

represent domain failures with domain/application exceptions, not HTTP-specific exceptions in application or domain code
map exceptions to HTTP status codes in the web/API layer with
```
@ControllerAdvice
```
and
```
@ExceptionHandler
```
use
```
ResponseStatusException
```
only for small web/API-local cases; prefer centralized exception mapping for reusable APIs
for Spring Boot 3+, prefer
```
ProblemDetail
```
for structured API errors when the project already uses Spring Framework 6 error conventions or when adding a new API error format
never construct successful and error response payloads ad hoc across multiple controllers when a shared error format exists

在应用或领域代码中使用领域/应用异常表示领域失败，而非HTTP特定异常
在Web/API层通过
```
@ControllerAdvice
```
和
```
@ExceptionHandler
```
将异常映射为HTTP状态码
仅对于小型的Web/API局部场景使用
```
ResponseStatusException
```
；对于可复用的API，优先使用集中式异常映射
对于Spring Boot 3+，当项目已使用Spring Framework 6的错误约定或新增API错误格式时，优先使用
```
ProblemDetail
```
返回结构化API错误
当存在共享错误格式时，绝不要在多个控制器中临时构造成功和错误响应payload

JSON Serialization

JSON 序列化

use Jackson as the default JSON mechanism in Spring Boot applications
map JSON at the web/API edge to request/response DTOs or command/query objects; do not bind external API shapes directly to rich domain entities unless the API is intentionally internal
prefer records for immutable request/response DTOs when validation, serialization, and project style allow it
keep Jackson annotations at the DTO/API model level when possible; avoid polluting domain entities with transport-specific JSON annotations unless persistence/API compatibility requires it
use
```
@JsonFormat
```
,
```
@JsonProperty
```
, and custom serializers sparingly and only when the API contract requires them

Spring Boot应用中默认使用Jackson作为JSON处理机制
在Web/API边缘将JSON映射到请求/响应DTO或命令/查询对象；不要将外部API结构直接绑定到富领域实体，除非该API是明确的内部API
当校验、序列化和项目风格允许时，优先使用record作为不可变的请求/响应DTO
尽可能将Jackson注解保留在DTO/API模型层面；避免用传输特定的JSON注解污染领域实体，除非持久化/API兼容性有要求
尽量少用
```
@JsonFormat
```
、
```
@JsonProperty
```
和自定义序列化器，仅当API契约有要求时使用

Validation

校验

use Bean Validation on request DTOs for syntactic request validation
place business validation in application/domain code so it remains independent of HTTP and can be tested without Spring MVC
use
```
@Valid
```
or
```
@Validated
```
at controller entry points when consuming validated request bodies or parameters
do not use validation annotations as the only enforcement for domain invariants that must hold outside HTTP requests

在请求DTO上使用Bean Validation进行语法层面的请求校验
将业务校验放在应用/领域代码中，使其独立于HTTP，无需Spring MVC即可测试
消费已校验的请求体或参数时，在控制器入口点使用
```
@Valid
```
或
```
@Validated
```
对于必须在HTTP请求之外也保持成立的领域不变量，不要仅依赖校验注解作为唯一强制手段

Configuration

配置

use
```
application.yml
```
or
```
application.properties
```
consistently with the existing project
prefer typed
```
@ConfigurationProperties
```
over scattered
```
@Value
```
fields when more than one related property is used
keep environment-specific values in profiles, environment variables, or deployment configuration, not hardcoded in source
do not introduce new profiles, property namespaces, or configuration files without checking existing conventions first
avoid reading configuration directly from deep domain code; inject typed configuration into Spring-managed components or adapters that need it

与现有项目保持一致，使用
```
application.yml
```
或
```
application.properties
```
当相关属性超过一个时，优先使用类型安全的
```
@ConfigurationProperties
```
，而非分散的
```
@Value
```
字段
将环境特定的值放在profile、环境变量或部署配置中，不要硬编码在源码里
未检查现有约定前，不要引入新的profile、属性命名空间或配置文件
避免在深层领域代码中直接读取配置；将类型安全的配置注入到需要它的Spring管理组件或适配器中

Observability

可观测性

use Spring Boot Actuator for health, info, metrics, and readiness/liveness endpoints when observability is needed
create custom health indicators near the component, feature, adapter, or integration whose health they expose
create metrics with Micrometer and prefer OpenTelemetry-compatible naming and labels
avoid high-cardinality metric tags such as user ids, request ids, emails, or raw URLs
log at application edges for incoming/outgoing integration events and in application services for meaningful business milestones; do not log sensitive data

需要可观测性能力时，使用Spring Boot Actuator提供健康检查、信息、指标以及就绪/存活端点
将自定义健康检查指示器放置在它们所监控的组件、功能、适配器或集成点附近
使用Micrometer创建指标，优先采用兼容OpenTelemetry的命名和标签
避免使用高基数的指标标签，例如用户ID、请求ID、邮箱或原始URL
在应用边缘记录入站/出站集成事件的日志，在应用服务中记录有意义的业务里程碑；不要记录敏感数据

Security

安全

use Spring Security when authentication or authorization is needed
keep authorization decisions close to controllers, handlers, or application use cases; do not scatter role checks through domain entities
prefer method security for use-case authorization when it improves readability and testability
do not disable CSRF, CORS, authentication, or authorization globally unless the project context explicitly requires it and the user agrees
never add secrets, tokens, passwords, or private keys to source files or test fixtures

需要认证或授权时使用Spring Security
将授权决策放在靠近控制器、处理器或应用用例的位置；不要在领域实体中分散角色检查
当能提升可读性和可测试性时，优先使用方法级安全进行用例授权
除非项目上下文明确要求且用户同意，否则不要全局禁用CSRF、CORS、认证或授权
绝不要在源文件或测试固件中添加密钥、令牌、密码或私钥

Testing

测试

write unit tests for application/domain behavior without starting the Spring context when possible
write Spring MVC slice tests with
```
@WebMvcTest
```
for controller behavior and HTTP mapping
write persistence slice tests with
```
@DataJpaTest
```
when verifying repository/query behavior
write integration tests with
```
@SpringBootTest
```
only when the Spring container, configuration, wiring, or end-to-end behavior is the subject under test
use Testcontainers when external infrastructure is needed and the project already uses it or the user approves adding it
do not overuse
```
@MockBean
```
/
```
@MockitoBean
```
; prefer smaller unit tests or focused slices when possible
integration tests should follow the project's naming convention; when there is no convention, use
```
*IT
```
for integration tests and keep unit tests as
```
*Test
```
execute relevant tests after every meaningful change unless the user explicitly activates demo/showtime mode

尽可能在不启动Spring上下文的情况下为应用/领域行为编写单元测试
使用
```
@WebMvcTest
```
编写Spring MVC切片测试，验证控制器行为和HTTP映射
验证仓库/查询行为时，使用
```
@DataJpaTest
```
编写持久化切片测试
仅当测试对象是Spring容器、配置、装配或端到端行为时，才使用
```
@SpringBootTest
```
编写集成测试
当需要外部基础设施且项目已使用Testcontainers或用户同意添加时，使用Testcontainers
不要过度使用
```
@MockBean
```
/
```
@MockitoBean
```
；尽可能优先使用小型单元测试或聚焦的切片测试
集成测试应遵循项目的命名约定；无约定时，集成测试使用
```
*IT
```
命名，单元测试保持
```
*Test
```
命名
每次有意义的变更后都要执行相关测试，除非用户明确启用了演示/展示模式

System Tests

系统测试

create system tests as a separate module or clearly separated test source set when the project already has that convention or when the service is tested as a deployed process
prefer HTTP clients already used by the project; otherwise use Spring
```
WebTestClient
```
,
```
RestClient
```
, or JDK
```
HttpClient
```
depending on the test boundary
system tests should exercise the running service through public interfaces, not through Spring internals
avoid RestAssured unless the project already standardizes on it
execute system tests after major service changes when feasible

当项目已有相关约定或服务需要作为已部署进程进行测试时，将系统测试创建为独立模块或明确分离的测试源码集
优先使用项目已有的HTTP客户端；否则根据测试边界选择Spring
```
WebTestClient
```
、
```
RestClient
```
或JDK
```
HttpClient
```
系统测试应通过公共接口测试运行中的服务，而非通过Spring内部机制
避免使用RestAssured，除非项目已将其作为标准
可行的话，在服务重大变更后执行系统测试

README Guidelines

README 规范

write brief, to-the-point README.md files for advanced developers
use precise and concise language; avoid generic adjectives like "simple" or "lightweight"
do not include detailed project structure file/folder listings; high-level module descriptions are acceptable
do not list every REST endpoint in READMEs; link to API docs when present
if modules are listed, provide links
do not use the term "Orchestrates"; use more specific alternatives

为高级开发者编写简洁、切题的README.md文件
使用精确简洁的语言；避免使用「简单」或「轻量」之类的泛泛形容词
不要包含详细的项目结构文件/文件夹列表；高层级的模块描述是可接受的
不要在README中列出所有REST端点；如果有API文档则提供链接
如果列出了模块，请提供链接
不要使用「Orchestrates」一词；使用更具体的替代表述

Project Management

项目管理

on opening existing projects, load
```
AGENTS.md
```
if present before making changes
do not create or change files on opening existing projects; stop after initialization and wait for instructions when the user only asked to inspect or initialize
do not generate code initially in an empty project unless the user explicitly asks to scaffold or implement something
always inspect existing package, test, build, and dependency conventions before adding code
keep changes minimal and aligned with the project's current Spring Boot major version
do not migrate between Spring Boot major versions unless the user explicitly requests a migration

打开现有项目时，如果存在
```
AGENTS.md
```
则先加载该文件再进行变更
打开现有项目时不要创建或修改文件；如果用户仅要求检查或初始化，则在初始化后停止，等待进一步指令
不要在空项目中初始生成代码，除非用户明确要求搭建脚手架或实现某些功能
添加代码前始终检查现有的包、测试、构建和依赖约定
保持变更最小化，且与项目当前的Spring Boot主版本保持一致
除非用户明确要求迁移，否则不要在Spring Boot主版本之间进行迁移