full-stack-skills/skills/java-code-comments/templates/feign-service-comment-template.md

Feign Service Interface 类注释模板

类注释模板

Java 编程规范格式（严格）

/**
 * {服务名称}Feign远程服务接口
 *
 * <p>通过Feign调用{目标服务}的远程接口</p>
 * <p>主要功能:</p>
 * <ul>
 *   <li>{接口功能1}</li>
 *   <li>{接口功能2}</li>
 * </ul>
 *
 * @author system
 * @since 2025-01-21
 */
@FeignClient(name = "{service-name}", path = "/api/{resource}")
public interface [Resource]FeignService {
}

标准 JavaDoc 格式

/**
 * {服务名称}Feign远程服务接口
 * 
 * <p>通过Feign调用{目标服务}的远程接口
 * 
 * <p>主要功能:
 * <ul>
 *   <li>{接口功能1}</li>
 *   <li>{接口功能2}</li>
 * </ul>
 * 
 * @author [作者名]
 * @since [版本号或日期]
 */
@FeignClient(name = "{service-name}", path = "/api/{resource}")
public interface [Resource]FeignService {
}

方法注释模板

GET 请求方法

Java 编程规范格式（严格）

/**
 * <p>查询{资源名称}</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，查询{资源名称}信息。</p>
 * 
 * @param id java.lang.Long {资源名称}唯一标识符
 * @return [Resource]DTO {返回类型} {资源名称}信息 DTO
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@GetMapping("/{id}")
[Resource]DTO get[Resource](@PathVariable("id") Long id);

标准 JavaDoc 格式

/**
 * 查询{资源名称}
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，查询{资源名称}信息。
 * 
 * @param id {资源名称}唯一标识符
 * @return {资源名称}信息 DTO
 * @throws FeignException 当远程调用失败时抛出
 */
@GetMapping("/{id}")
[Resource]DTO get[Resource](@PathVariable("id") Long id);

POST 请求方法

Java 编程规范格式（严格）

/**
 * <p>创建{资源名称}</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，创建{资源名称}。</p>
 * 
 * @param request [Resource]CreateRequest {资源名称}创建请求对象
 * @return [Resource]DTO {返回类型} 创建成功的{资源名称}信息 DTO
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@PostMapping
[Resource]DTO create[Resource](@RequestBody [Resource]CreateRequest request);

标准 JavaDoc 格式

/**
 * 创建{资源名称}
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，创建{资源名称}。
 * 
 * @param request {资源名称}创建请求对象
 * @return 创建成功的{资源名称}信息 DTO
 * @throws FeignException 当远程调用失败时抛出
 */
@PostMapping
[Resource]DTO create[Resource](@RequestBody [Resource]CreateRequest request);

PUT 请求方法

Java 编程规范格式（严格）

/**
 * <p>更新{资源名称}</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，更新{资源名称}信息。</p>
 * 
 * @param id java.lang.Long {资源名称}唯一标识符
 * @param request [Resource]UpdateRequest {资源名称}更新请求对象
 * @return [Resource]DTO {返回类型} 更新后的{资源名称}信息 DTO
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@PutMapping("/{id}")
[Resource]DTO update[Resource](@PathVariable("id") Long id, @RequestBody [Resource]UpdateRequest request);

标准 JavaDoc 格式

/**
 * 更新{资源名称}
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，更新{资源名称}信息。
 * 
 * @param id {资源名称}唯一标识符
 * @param request {资源名称}更新请求对象
 * @return 更新后的{资源名称}信息 DTO
 * @throws FeignException 当远程调用失败时抛出
 */
@PutMapping("/{id}")
[Resource]DTO update[Resource](@PathVariable("id") Long id, @RequestBody [Resource]UpdateRequest request);

DELETE 请求方法

Java 编程规范格式（严格）

/**
 * <p>删除{资源名称}</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，删除{资源名称}。</p>
 * 
 * @param id java.lang.Long {资源名称}唯一标识符
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@DeleteMapping("/{id}")
void delete[Resource](@PathVariable("id") Long id);

标准 JavaDoc 格式

/**
 * 删除{资源名称}
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，删除{资源名称}。
 * 
 * @param id {资源名称}唯一标识符
 * @throws FeignException 当远程调用失败时抛出
 */
@DeleteMapping("/{id}")
void delete[Resource](@PathVariable("id") Long id);

查询列表方法

Java 编程规范格式（严格）

/**
 * <p>查询{资源名称}列表</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，查询{资源名称}列表，支持{查询条件}等条件筛选。</p>
 * 
 * @param query [Resource]QueryRequest {资源名称}查询请求对象，包含查询条件
 * @return java.util.List&lt;[Resource]DTO&gt; {返回类型} {资源名称}列表
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@GetMapping("/list")
List<[Resource]DTO> list[Resource]([Resource]QueryRequest query);

标准 JavaDoc 格式

/**
 * 查询{资源名称}列表
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，查询{资源名称}列表，支持{查询条件}等条件筛选。
 * 
 * @param query {资源名称}查询请求对象，包含查询条件
 * @return {资源名称}列表
 * @throws FeignException 当远程调用失败时抛出
 */
@GetMapping("/list")
List<[Resource]DTO> list[Resource]([Resource]QueryRequest query);

分页查询方法

Java 编程规范格式（严格）

/**
 * <p>分页查询{资源名称}列表</p>
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，分页查询{资源名称}列表。</p>
 * 
 * @param query [Resource]QueryRequest {资源名称}查询请求对象，包含分页参数和查询条件
 * @return com.baomidou.mybatisplus.core.metadata.IPage&lt;[Resource]DTO&gt; {返回类型} 分页结果，包含{资源名称}列表和分页信息
 * @exception com.example.exception.FeignException 当远程调用失败时抛出
 */
@PostMapping("/page")
IPage<[Resource]DTO> page[Resource](@RequestBody [Resource]QueryRequest query);

标准 JavaDoc 格式

/**
 * 分页查询{资源名称}列表
 * 
 * <p>通过Feign调用{目标服务}的{接口路径}接口，分页查询{资源名称}列表。
 * 
 * @param query {资源名称}查询请求对象，包含分页参数和查询条件
 * @return 分页结果，包含{资源名称}列表和分页信息
 * @throws FeignException 当远程调用失败时抛出
 */
@PostMapping("/page")
IPage<[Resource]DTO> page[Resource](@RequestBody [Resource]QueryRequest query);

使用说明

1. 替换占位符：

   • {服务名称} - 替换为实际的服务名称，如"用户"、"订单"等
   • {目标服务} - 替换为实际的目标服务名称，如"用户服务"、"订单服务"等
   • {service-name} - 替换为实际的 Feign 服务名称（配置中的服务名）
   • {resource} - 替换为实际的资源路径
   • {资源名称} - 替换为实际的资源名称，如"用户"、"订单"等
   • [Resource] - 替换为实际的类名，如"User"、"Order"等
   • {接口功能} - 替换为实际的接口功能描述
   • {接口路径} - 替换为实际的接口路径

2. 选择格式：

   • 如果项目遵循《JAVA 编程规范》，使用"Java 编程规范格式（严格）"
   • 如果项目使用标准 JavaDoc，使用"标准 JavaDoc 格式"

3. 方法注释：

   • Feign 接口方法注释应明确说明调用的目标服务和接口路径
   • 所有方法都应说明可能抛出的 FeignException
   • 参数和返回值应与远程服务接口保持一致

4. Feign 接口特点：

   • 接口方法通常对应远程服务的 REST API
   • 方法签名应与远程服务接口保持一致
   • 异常处理通常统一为 FeignException
   • 需要配置正确的 @FeignClient 注解参数