Spring Cloud OpenFeign 常用注解_笔记

Spring Cloud OpenFeign 提供了一种声明式、模板化的HTTP客户端，可以通过简单的接口描述远程调用，而不必手动编写低级的 HTTP 客户端代码。FeignClient用法参考：FeignClient用法-笔记-CSDN博客。这里梳理Spring Cloud OpenFeign 常用注解。

1. @FeignClient

功能：声明一个Feign客户端，用于访问远程服务。
适用场景：定义需要调用的其他微服务的接口。
注意事项：

• name 或 value 属性指定服务名（在服务注册中心注册的名称）。
• 可以配置URL直接指定地址（用于测试或非注册中心场景）。
• 支持配置降级处理（通过fallback或fallbackFactory）。

示例：

@FeignClient(name = "user-service", url = "http://localhost:8080", fallback = UserClientFallback.class)
public interface UserClient {
    
    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);
}

// 降级实现
@Component
public class UserClientFallback implements UserClient {
    @Override
    public User getUserById(Long id) {
        return new User(0L, "默认用户");
    }
}

2. @RequestMapping 及变种

 @RequestMapping 及变种 (@GetMapping, @PostMapping 等):

功能：指定Feign客户端方法对应的HTTP方法和路径。
适用场景：定义远程调用的具体端点。
注意事项：

• 与Spring MVC中的用法一致，但用于Feign客户端接口。
• 路径中可以使用占位符（配合@PathVariable使用）。

示例：

@FeignClient(name = "order-service")
public interface OrderClient {

    @PostMapping("/orders")
    Order createOrder(@RequestBody Order order);

    @GetMapping("/orders/{orderId}")
    Order getOrder(@PathVariable("orderId") String orderId);
}

3. @PathVariable

功能：将方法参数绑定到URI模板变量。
适用场景：当URL路径中包含动态变量时（如RESTful风格）。
注意事项：

• 必须指定value或name属性来匹配URI模板中的变量名（与 MVC 不同，在Feign中必须显式指定，不能省略）。
• 不支持 Spring MVC 的 @PathVariable(required = false)
• 路径变量不能为空

示例：

@FeignClient(name = "product-service")
public interface ProductClient {
    
    @GetMapping("/products/{productId}")
    Product getProduct(@PathVariable("productId") Long id); // 注意：这里必须指定"productId"
}

4. @RequestHeader

功能：将方法参数绑定到HTTP请求头。
适用场景：需要传递自定义HTTP头信息（如认证token）。

• 传递认证令牌（Authorization）
• 设置内容协商头（Accept）
• 自定义业务标识头

注意事项：

• 可以传递单个值，也可以传递Map来设置多个请求头。
• 支持占位符表达式
• 不会被 Spring MVC 的 @RequestHeader 解析
• 如果请求头的值是动态的，必须用@RequestHeader注解。

示例：

@FeignClient(name = "auth-service")
public interface AuthClient {

    @GetMapping("/userinfo")
    UserInfo getUserInfo(@RequestHeader("Authorization") String token);
    
    // 传递多个请求头
    @PostMapping("/update")
    void update(@RequestHeader Map<String, String> headers, @RequestBody UserInfo userInfo);
}

5. @RequestParam

功能：将方法参数绑定到HTTP请求参数（URL查询参数）。
适用场景：

• 传递单个或少量查询参数。
• 非结构化参数传递
• 数组/集合类型参数

注意事项：

• 数组参数格式：?ids=1,2,3 或 ?ids=1&ids=2
• 如果参数是可选，需要设置required=false（默认是true）。
• 当参数较多时，建议使用@SpringQueryMap代替。

示例：

@FeignClient(name = "search-service")
public interface SearchClient {

    @GetMapping("/search")
    List<Product> searchProducts(@RequestParam("kw") String keyword, 
                                @RequestParam(value = "page", required = false, defaultValue = "0") int page);

    // 数组参数
    @DeleteMapping("/items")
    void deleteItems(@RequestParam("ids") List<Long> ids);
}

6. @SpringQueryMap 

功能：将POJO对象转换为URL查询参数。当我们需要将一个对象作为查询参数传递给另一个服务时，使用这个注解可以避免手动拼接URL查询字符串。
适用场景：

• 在Feign客户端中，需要传递多个查询参数，而这些参数被封装在一个对象中。
• 传递复杂或多条件的查询参数（避免在方法中写多个@RequestParam）。

注意事项：

• 支持嵌套对象的转换（通过点号.连接属性，如user.address.city）。
• 只能用于Feign客户端。
• 适用于GET请求，因为GET请求通常使用查询参数传递数据。
• GET 请求参数长度限制（约 2048 字符）

示例：

@FeignClient(name = "user-service")
public interface UserClient {
    
    @GetMapping("/users/search")
    List<User> searchUsers(@SpringQueryMap UserSearchCriteria criteria);
}

// 查询条件POJO
public class UserSearchCriteria {
    private String name;
    private Integer age;
    private Address address; // 嵌套对象

    // getters and setters
}

public class Address {
    private String city;
    private String street;
    // getters and setters
}

//当我们调用userClient.searchUsers(new UserQuery("张三", 25,new Address("beijing","xierqi")))时，
//Feign会生成一个URL：/users?name=张三&age=25&address.city=beijing&address.street=xierqi。

补充说明:

在Spring MVC中，如果我们想在Controller的方法中接收多个查询参数，可以直接使用一个POJO对象作为参数，而不需要任何注解，Spring MVC会自动将查询参数绑定到对象中（但要求该对象有默认构造函数，并且属性名与查询参数名匹配）。例如：

@Controller
public class UserController {

    @GetMapping("/users/search")
    List<User> searchUsers(UserSearchCriteria criteria){
        //......
    }
}

但是，在Feign客户端中，我们不能直接这样做，因为Feign默认不会将对象转换为查询参数，所以需要使用@SpringQueryMap注解。

总结：

使用这些注解，可以方便地定义Feign客户端，实现微服务之间的优雅调用。常见用法总结：

1. 服务间调用：首选 @FeignClient + Spring Cloud 服务发现
2. GET 参数：
   • 简单参数 → @RequestParam
   • 复杂参数 → @SpringQueryMap
3. 路径参数：必须显式命名 @PathVariable("id")
4. 请求头：动态头用 @RequestHeader
5. 特殊格式：
   • 表单 → 自定义 Encoder
   • 文件 → @RequestPart（需额外配置）
6. 错误处理：
   • 熔断降级 → fallback/fallbackFactory
   • 错误解码 → 实现 ErrorDecoder

一个完整示例：

// 完整示例
@FeignClient(
  name = "user-service",
  fallbackFactory = UserClientFallbackFactory.class
)
public interface UserClient {
    @GetMapping("/users/{userId}")
    User getUser(
        @PathVariable("userId") String id,
        @RequestHeader("X-Trace-Id") String traceId
    );

    @PostMapping("/users/search")
    List<User> searchUsers(
        @SpringQueryMap UserQuery query,
        @RequestHeader Map<String, String> headers
    );
}

@Component
public class UserClientFallbackFactory implements FallbackFactory<UserClient> {
    @Override
    public UserClient create(Throwable cause) {
        return new UserClient() {
            @Override
            public User getUser(String id, String traceId) {
                return new User("fallback-user");
            }
            // ...其他方法降级实现
        };
    }
}

相关阅读：

• FeignClient用法-笔记-CSDN博客
• Spring MVC中常用注解_笔记-CSDN博客