Spring Cloud的Feign客户端入门


在本教程中，我们将了解FeignClient以及如何在Spring Boot/Spring Cloud应用程序中使用它。
FeignClient是一个以声明方式创建REST API客户端的库。因此，如果我们不是手动编写远程API客户端，就可能使用Springs RestTemplate，而使用Feign声明客户端定义很方便，其余部分在运行时生成供使用。

我们将构建一个小型命令行应用程序，它模拟我们一个看板API的完整测试。示例应用程序将创建一个新用户，登录，检索所有板并再次注销用户。它捕获了最常见的用例（POST，GET，DELETE + AuthN）

添加依赖项
我们在本教程中使用Maven。由于我们不想弄乱版本号，最简单的方法是在Maven POM 中的dependencyManagement中包含Spring Cloud设置。

<dependencyManagement> 
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>  
      <artifactId>spring-cloud-dependencies</artifactId> 
      <version>Finchley.SR1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

现在，我们可以使用经典的Spring Boot启动程序将依赖项添加到Feign：

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

Feign客户端使用声明方法来访问API。要使用它，我们必须首先在我们的Spring Boot应用程序上使用@EnableFeignClients注解启用S​​pring Cloud支持。

@SpringBootApplication
@EnableFeignClients 
public class FeignIntroductionApplication implements ApplicationRunner 
{ //omitted 
}

下一步是声明用于访问我们的API的接口。我们将其命名为KanbanClient，因为它将提供调用远程API的方法。

@FeignClient(name="KanbanClient", 
             url= "https://kanbanbackend.herokuapp.com/") 
public interface KanbanClient { }

要将其转换为Feign客户端，我们必须在界面上设置@FeignClient注释，并为其指定名称属性，并使用url属性设置远程URL 。这里支持SpEL，因此我们可以将值外部化为属性文件。我们也可以使用Eureka在这里使用服务发现，而不是使用URL，如果使用Eureka服务发现，这里只要：

@FeignClient("KanbanApp")

KanbanApp是注册在Eureka服务注册器里面的应用名称，也就是对方生产者Srping.application.name=KanbanApp中配置的名称。

下面要定义远程调用的各个方法，不同远程API对应不同的接口方法，需要使用Spring MVC中的一些注释，这些注释通常也是用在REST服务器端的@Controller上。它们的行为相同，这里只是用在REST客户端。

POST
在方法上添加@PostMapping批注并在其中传递参数，将该方法转换为POST调用。在PostMapping注释中，我们提供了相对于在@FeignClient注释上设置的URL的端点（具体URL路径）。

@PostMapping(value = "/register")
String registerUser(User user);

用户是一个简单的POJO，带有用户名和密码字段。Feign，Spring会自动将其转换为JSON。

GET
原理与上面相同，但我们在方法上使用@GetMapping。我们还发送了身份验证标头。API使用X-Auth-Token。

@GetMapping("/boards")
List<Board> listBoards(
  @RequestHeader("X-Auth-Token") 
  String authHeader
);

 /boards将返回用户的所有看板板的列表。Board是POJO，仅包含id和name。

PUT
同样，这次只需使用@PutMapping注释。

@PutMapping("/board/{id}")
Board changeBoard(
  @RequestHeader("X-Auth-Token") String authHeader, 
  @PathVariable("id") Long id, 
  Board board
);

我们可以通过将PUT提交看板的端点（/ board / {id}）实现更改看板的名称。路径变量请参见下面的使用变量进行调用部分。

DELETE
只需要@DeleteMapping注释。

@DeleteMapping("/unregister")
ResponseEntity<Void> unregisterUser(
  @RequestHeader("X-Auth-Token") String authToken, 
  Confirmation user
);

此端点需要具有用户密码的Confirmation对象才能删除该帐户，并且如果成功则还需要返回200。


使用变量进行调用
如果我们的端点需要基于像ids这样的实体的变量，我们可以在方法参数上使用@PathVariable注释。它的行为与Spring MVC @Controllers相同。
然后可以在@PutMapping的端点声明中使用已定义的变量如：

@PutMapping("/board/{id}") 
Board changeBoard(
  @RequestHeader("X-Auth-Token") String authHeader, 
  @PathVariable("id") Long id, 
  Board board
);

通过身份认证调用
我们将使用登录端点。它要求用户凭据作为基本身份验证发送，并将返回令牌以进行进一步身份验证。当我们成功调用/ login端点时，它将在响应头中返回auth令牌：

@PostMapping("/login")
ResponseEntity<Void> loginUser(
  @RequestHeader("Authorization") String authHeader
);

向下传递附加信息的第一种方法是在其上添加带有@RequestHeader注释的方法参数。参数的值将设置为注释中定义的HTTP标头的值。
在身份认证的情况下，它是Authorization标头。作为一个值，我们给它基本的auth编码字符串。
在随后的Kanban API调用中，我们将使用带有令牌的X-Auth-Token标头。
响应头不能作为方法返回值直接返回，但我们可以使用Spring的ResponseEntity，它是一个响应包装器。由于我们的端点不会在响应主体中返回任何内容，因此需要将Void作为参数化类型。
当在看板API中使用Spring Session时，需要通过X-Auth-Token标头交换auth令牌。
要检索我们调用的值：

String token = response.getHeaders().getFirst("X-Auth-Token");


其他认证方法
我们总是可以在每个方法上使用@RequestHeader注释传递身份验证标头。但是，还有一种在全局范围内指定的替代方法。
像Spring MVC一样，Feign有一个拦截器概念，可用于在远程调用之前执行特定的操作。入口点是RequestInterceptor接口。
使用Spring，我们只需要提供一个Bean来实现Spring上下文的特定接口，它将自动被使用。

@Bean 
AuthInterceptor authFeign() { 
  return new AuthInterceptor(); 
}
class AuthInterceptor implements RequestInterceptor { 
  @Override 
  public void apply(RequestTemplate template) { 
    template.header("Authorization", "<your token>"); 
  }
}

我们的拦截器是一个Spring Bean，因此我们可以使用Spring的强大功能并将authN信息外部化为属性，甚至可以从会话范围的bean中检索它，我们会根据每个用户来保存信息。

使用FeignClient
现在，我们可以像任何其他Spring Bean一样将KanbanClient注入我们的代码中。在启动时，Spring Cloud将为我们设置Feign客户端并为我们提供常规的Spring Proxy，以便我们可以简单地开始使用远程端。
我们使用Feign的客户端代码最终看起来像这样：

@FeignClient(name="KanbanClient", 
             url= "https://kanbanbackend.herokuapp.com/")
public interface KanbanClient {
  @PostMapping(value = "/register") 
  String registerUser(User user); 
  @DeleteMapping("/unregister")
  ResponseEntity<Void> unregisterUser(
    @RequestHeader("X-Auth-Token") String authToken, 
    Confirmation user
  );
  @PostMapping("/login") 
  ResponseEntity<Void> loginUser(
    @RequestHeader("Authorization") String authHeader
  );
  @GetMapping("/boards")
  List<Board> listBoards(
    @RequestHeader("X-Auth-Token") String authHeader
  );
  @PostMapping("/boards") 
  Board createBoard(
    @RequestHeader("X-Auth-Token") String authHeader,
    Board board
  );
  @PutMapping("/board/{id}")
  Board changeBoard(
    @RequestHeader("X-Auth-Token") String authHeader, 
    @PathVariable("id") Long id,
    Board board
  );
}

完整的源码在GitHub上