Controller 类注释模板
类注释模板
标准 JavaDoc 格式
/**
* [资源名称]控制器
*
* <p>提供[资源名称]相关的 REST API 接口，包括[主要功能列表]。
* 本控制器遵循 RESTful 设计规范，使用标准的 HTTP 方法进行资源操作。
*
* <p>主要功能：
* <ul>
* <li>[功能1]</li>
* <li>[功能2]</li>
* <li>[功能3]</li>
* </ul>
*
* @author [作者名]
* @since [版本号或日期]
*/
Java 编程规范格式（严格）
/**
* <p>[资源名称]控制器</p>
*
* <p>提供[资源名称]相关的 REST API 接口，包括[主要功能列表]。
* 本控制器遵循 RESTful 设计规范，使用标准的 HTTP 方法进行资源操作。</p>
*
* <p>主要功能：
* <ul>
* <li>[功能1]</li>
* <li>[功能2]</li>
* <li>[功能3]</li>
* </ul>
* </p>
*
* @author [作者名]
* @since [版本号或日期]
*/
字段注释模板
/**
* [服务名称]
*
* <p>用于处理[资源名称]相关的业务逻辑
*/
private final [ServiceType] [serviceName];
方法注释模板
POST 方法（创建资源）
标准 JavaDoc 格式
/**
* 创建[资源名称]
*
* <p>接收[资源名称]创建请求，验证数据后创建新[资源名称]并返回[资源名称]信息。
*
* @param request [资源名称]创建请求对象，包含[字段列表]等信息
* @return 创建成功的[资源名称]信息 DTO
* @throws IllegalArgumentException 当请求参数不合法时抛出
* @throws BusinessException 当[业务规则]时抛出
*/
@PostMapping
public [ResourceDTO] create[Resource](@RequestBody [Resource]CreateRequest request) {
}
Java 编程规范格式（严格）
/**
* <p>创建[资源名称]</p>
*
* <p>接收[资源名称]创建请求，验证数据后创建新[资源名称]并返回[资源名称]信息。</p>
*
* @param request com.example.dto.[Resource]CreateRequest [资源名称]创建请求对象，包含[字段列表]等信息
* @return com.example.dto.[Resource]DTO 创建成功的[资源名称]信息 DTO
* @exception java.lang.IllegalArgumentException 当请求参数不合法时抛出
* @exception com.example.exception.BusinessException 当[业务规则]时抛出
*/
@PostMapping
public [ResourceDTO] create[Resource](@RequestBody [Resource]CreateRequest request) {
}
GET 方法（查询资源）
标准 JavaDoc 格式
/**
* 根据[资源名称] ID 查询[资源名称]信息
*
* <p>根据提供的[资源名称] ID 查询对应的[资源名称]详细信息。
*
* @param id [资源名称]唯一标识符
* @return [资源名称]信息 DTO，包含[资源名称]的基本信息
* @throws ResourceNotFoundException 当[资源名称]不存在时抛出
*/
@GetMapping("/{id}")
public [ResourceDTO] get[Resource]ById(@PathVariable Long id) {
}
Java 编程规范格式（严格）
/**
* <p>根据[资源名称] ID 查询[资源名称]信息</p>
*
* <p>根据提供的[资源名称] ID 查询对应的[资源名称]详细信息。</p>
*
* @param id java.lang.Long [资源名称]唯一标识符，不能为null
* @return com.example.dto.[Resource]DTO [资源名称]信息 DTO，包含[资源名称]的基本信息
* @exception com.example.exception.ResourceNotFoundException 当[资源名称]不存在时抛出
*/
@GetMapping("/{id}")
public [ResourceDTO] get[Resource]ById(@PathVariable Long id) {
}
PUT 方法（更新资源）
/**
* 更新[资源名称]信息
*
* <p>根据[资源名称] ID 和更新请求，更新[资源名称]的指定字段信息。
*
* @param id [资源名称]唯一标识符
* @param request [资源名称]更新请求对象，包含需要更新的字段信息
* @return 更新后的[资源名称]信息 DTO
* @throws ResourceNotFoundException 当[资源名称]不存在时抛出
* @throws IllegalArgumentException 当更新参数不合法时抛出
*/
@PutMapping("/{id}")
public [ResourceDTO] update[Resource](@PathVariable Long id, @RequestBody [Resource]UpdateRequest request) {
}
DELETE 方法（删除资源）
/**
* 删除[资源名称]
*
* <p>根据[资源名称] ID 删除指定的[资源名称]。删除操作会级联删除[资源名称]相关的数据。
*
* @param id [资源名称]唯一标识符
* @throws ResourceNotFoundException 当[资源名称]不存在时抛出
*/
@DeleteMapping("/{id}")
public void delete[Resource](@PathVariable Long id) {
}
使用示例
标准 JavaDoc 格式示例
/**
* 用户管理控制器
*
* <p>提供用户相关的 REST API 接口，包括用户的创建、查询、更新和删除操作。
* 本控制器遵循 RESTful 设计规范，使用标准的 HTTP 方法进行资源操作。
*
* <p>主要功能：
* <ul>
* <li>创建新用户</li>
* <li>根据 ID 查询用户信息</li>
* <li>更新用户信息</li>
* <li>删除用户</li>
* </ul>
*
* @author System
* @since 1.0.0
*/
@RestController
@RequestMapping("/api/users")
public class UserController {
/**
* 用户服务接口
*
* <p>用于处理用户相关的业务逻辑
*/
private final UserService userService;
/**
* 构造函数
*
* @param userService 用户服务实例，由 Spring 容器注入
*/
public UserController(UserService userService) {
this.userService = userService;
}
/**
* 创建新用户
*
* <p>接收用户创建请求，验证数据后创建新用户并返回用户信息。
*
* @param request 用户创建请求对象，包含用户名、邮箱、密码等信息
* @return 创建成功的用户信息 DTO
* @throws IllegalArgumentException 当请求参数不合法时抛出
* @throws BusinessException 当用户名或邮箱已存在时抛出
*/
@PostMapping
public UserDTO createUser(@RequestBody UserCreateRequest request) {
return userService.createUser(request);
}
}
Java 编程规范格式示例（严格）
/**
* <p>用户管理控制器</p>
*
* <p>提供用户相关的 REST API 接口，包括用户的创建、查询、更新和删除操作。
* 本控制器遵循 RESTful 设计规范，使用标准的 HTTP 方法进行资源操作。</p>
*
* <p>主要功能：
* <ul>
* <li>创建新用户</li>
* <li>根据 ID 查询用户信息</li>
* <li>更新用户信息</li>
* <li>删除用户</li>
* </ul>
* </p>
*
* @author System
* @since 1.0.0
*/
@RestController
@RequestMapping("/api/users")
public class UserController {
/**
* <p>用户服务接口</p>
*
* <p>用于处理用户相关的业务逻辑</p>
*/
private final UserService userService;
/**
* <p>构造函数</p>
*
* @param userService com.example.service.UserService 用户服务实例，由 Spring 容器注入
*/
public UserController(UserService userService) {
this.userService = userService;
}
/**
* <p>创建新用户</p>
*
* <p>接收用户创建请求，验证数据后创建新用户并返回用户信息。</p>
*
* @param request com.example.dto.UserCreateRequest 用户创建请求对象，包含用户名、邮箱、密码等信息
* @return com.example.dto.UserDTO 创建成功的用户信息 DTO
* @exception java.lang.IllegalArgumentException 当请求参数不合法时抛出
* @exception com.example.exception.BusinessException 当用户名或邮箱已存在时抛出
*/
@PostMapping
public UserDTO createUser(@RequestBody UserCreateRequest request) {
return userService.createUser(request);
}
}
