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 {@Overridepublic 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注解。

總結：

注解	功能	適用場景	注意事項
@FeignClient	聲明Feign客戶端	定義遠程服務調用接口	配置服務名、URL、降級等
@RequestMapping	指定HTTP方法和路徑	定義遠程調用的端點	支持各種HTTP方法注解變體
@PathVariable	綁定路徑變量	RESTful風格的URL路徑參數	必須顯式指定變量名
@RequestHeader	綁定請求頭	傳遞自定義頭信息（如認證token）	可傳遞單個頭或多個頭（Map）
@RequestParam	綁定查詢參數	傳遞少量查詢條件	可選參數需設置required=false
@SpringQueryMap	POJO轉查詢參數	傳遞復雜或多條件查詢	支持嵌套對象，只能用于Feign

使用這些注解，可以方便地定義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> {@Overridepublic UserClient create(Throwable cause) {return new UserClient() {@Overridepublic User getUser(String id, String traceId) {return new User("fallback-user");}// ...其他方法降級實現};}
}

相關閱讀：

• FeignClient用法-筆記-CSDN博客
• Spring MVC中常用注解_筆記-CSDN博客