深入了解feign(01)-使用入门
前言
feign的使用文档中,开篇第一句就是Feign makes writing java http clients easier,中文译为Feign使得写java http用户端更容易。言下之意,Feign其实是一个java http用户端的类库。
本文我们将对Feign做一个大概的理解,并对其基本用法进行掌握,后续章节我们将深入Feign的各种应用场景及源码,让我们不仅知其然,还要知其所以然。
为什么选择Feign
假如读者有用过Jersey、Spring或者CXF来实现web服务端,那么肯定会对他们通过注解方法来定义接口的方式大开眼界。那么,我们为什么选择Feign,它又有哪些优势呢?
Feign允许我们通过注解的方式实现http用户端的功能,给了我们除了Apache HttpComponents之外的另一种选择Feign能用最小的性能开销,让我们调用web服务器上基于文本的接口。同时允许我们自己设置编码器、解码器和错误解决器等等
Feign如何工作的呢
Feign通过注解和模板的方式来定义其工作方式,参数(包括url、method、request和response等)非常直观地融入到了模板中。虽然Feign设计成了只支持基于文本的接口,但正是它的这种局限降低了实现的复杂性。而我们写http用户端代码的时候,超过90%的场景是基于文本的接口调用。另一个方面,使用Feign还可以简化我们的单元测试。
基本用法
典型的用法如下所示。
public interface UserService { @RequestLine("GET /user/get?id={id}") User get(@Param("id") Long id);}public class User { Long id; String name;}public class Main { public static void main(String[] args) { UserService userService = Feign.builder() .options(new Request.Options(1000, 3500)) .retryer(new Retryer.Default(5000, 5000, 3)) .target(UserService.class, "http://api.server.com"); System.out.println("user: " + userService.get(1L)); }}Feign下面接口的注解
Feign通过注解和模板的方式来定义契约,那么又有哪些注解,分别是做什么用的呢?下面的表格参考了Feign官网的Annotation,给出了基本用法。
| Annotation | Interface Target | Usage |
|---|---|---|
| @RequestLine | Method | 用于定义method和uri模板,其值由@Param传入。 |
| @Param | Parameter | 模板变量,它的值将被用于替换表达式。 |
| @Headers | Method, Type | 用于定义header模板,其值由@Param传入。该注解可公告在Type上,也可公告在Method上。当公告在Type上时,相当于其下面的所有Method都公告了。当公告在Method上时,仅对当前Method有效。 |
| @QueryMap | Parameter | 可定义成一个key-value的Map,也可以定义成POJO,用以扩展进查询字符串。 |
| @HeaderMap | Parameter | 可定义成一个key-value的Map,用于扩展请求头。 |
| @Body | Method | 用于定义body模板,其值由@Param传入。 |
模板和表达式
模板和表达式模式,是基于URI Template – RFC 6570来实现的。表达式通过在方法上@Param修饰的参数来填充。
表达式必需以{}来包装变量名。也可使用正则表达式来验证,变量名+:+正则表达式的方式。表达式定义如下所示:
{name}{name:[a-zA-Z]*}
可以运用表达式的地方有下面几处。
@RequestLine@QueryMap@Headers@HeaderMap@Body
他们将遵循URI Template – RFC 6570规约。
- 未正确匹配的表达式将被忽略(忽略的意思就是,该变量在表达式中将被设置为null)
- 表达式值设置之前不会通过
Encoder进行编码 @Body使用的时候必需在Header里通过Content-Type指明内容类型
@Param有expander属性,该属性为Class类型,可以通过编码的方式更灵活地进行转换。假如返回的结果为null或者空字符串,表达式将被忽略。
public interface Expander { String expand(Object value);}另外,@Param可同时运用到多处,如下所示:
public interface ContentService { @RequestLine("GET /api/documents/{contentType}") @Headers("Accept {contentType}") String getDocumentByType(@Param("contentType") String type);}Feign的自己设置设置
可以通过Feign.builder()来自己设置设置少量阻拦器,用于加强其语义。比方我们可以添加超时阻拦器、编码阻拦器、解码阻拦器、重试阻拦器等等。如下所示:
interface Bank { @RequestLine("POST /account/{id}") Account getAccountInfo(@Param("id") String id);}public class BankService { public static void main(String[] args) { Bank bank = Feign.builder().decoder( new AccountDecoder()) .target(Bank.class, "https://api.examplebank.com"); }}Feign集成第三方组件
可以和很容易地和第三方组件结合使用,扩展了其功能,也添加了其灵活性。我们可以查阅官网文档,链接地址:integrations。
1. Gson
通过encoder和decoder来使用
public class Example { public static void main(String[] args) { GsonCodec codec = new GsonCodec(); GitHub github = Feign.builder() .encoder(new GsonEncoder()) .decoder(new GsonDecoder()) .target(GitHub.class, "https://api.github.com"); }}2. Jackson
和Gson一样,也是通过encoder和decoder来使用
public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .encoder(new JacksonEncoder()) .decoder(new JacksonDecoder()) .target(GitHub.class, "https://api.github.com"); }}3. JAXB
和Gson一样,也是通过encoder和decoder来使用
public class Example { public static void main(String[] args) { Api api = Feign.builder() .encoder(new JAXBEncoder()) .decoder(new JAXBDecoder()) .target(Api.class, "https://apihost"); }}4. JAX-RS
JAX-RS定义了自己的一套注解,我们可以通过和JAX-RS注解的集成来定义我们自己的注解皮肤。该功能需要结合contract使用。
interface GitHub { @GET @Path("/repos/{owner}/{repo}/contributors") List<Contributor> contributors(@PathParam("owner") String owner, @PathParam("repo") String repo);}public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .contract(new JAXRSContract()) .target(GitHub.class, "https://api.github.com"); }}5. OkHttp
OkHttp是一个http用户端类库,我们也可以将其包装成Feign的形式。该功能需要结合client来使用。
public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .client(new OkHttpClient()) .target(GitHub.class, "https://api.github.com"); }}6. Ribbon
Ribbon提供了用户端负载均衡功能。我们也可以和其一起集成使用。
public class Example { public static void main(String[] args) { MyService api = Feign.builder() .client(RibbonClient.create()) .target(MyService.class, "https://myAppProd"); }}7. Hystrix
Hystrix是一个断路器组件,为了保证分布式系统的健壮性,在某少量服务不可用的情况下,可避免出现雪崩效应。也可以和Feign结合使用
public class Example { public static void main(String[] args) { MyService api = HystrixFeign.builder().target(MyService.class, "https://myAppProd"); }}8. SOAP
SOAP是基于http之上的一种协议,其通信方式使用的是xml格式。
public class Example { public static void main(String[] args) { Api api = Feign.builder() .encoder(new SOAPEncoder(jaxbFactory)) .decoder(new SOAPDecoder(jaxbFactory)) .errorDecoder(new SOAPErrorDecoder()) .target(MyApi.class, "http://api"); }}9. SLF4J
slf4j是一个日志门面,给各种日志框架提供了统一的入口。
public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .logger(new Slf4jLogger()) .target(GitHub.class, "https://api.github.com"); }}Decoders
当我们的接口返回类型不为feign.Response、String、byte[]和void时,我们必需定义一个非默认的解码器。以Gson为例
public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .decoder(new GsonDecoder()) .target(GitHub.class, "https://api.github.com"); }}当我们想在feign.Response进行解码之前做少量事情,我们可以通过mapAndDecode来自己设置。
public class Example { public static void main(String[] args) { JsonpApi jsonpApi = Feign.builder() .mapAndDecode((response, type) -> jsopUnwrap(response, type), new GsonDecoder()) .target(JsonpApi.class, "https://some-jsonp-api.com"); }}Encoders
当我们定义的接口method为POST,且传入的类型不为String或者者byte[],我们需要自己设置编码器。同时需要在header上指明Content-Type。
static class Credentials { final String user_name; final String password; Credentials(String user_name, String password) { this.user_name = user_name; this.password = password; }}interface LoginClient { @RequestLine("POST /") void login(Credentials creds);}public class Example { public static void main(String[] args) { LoginClient client = Feign.builder() .encoder(new GsonEncoder()) .target(LoginClient.class, "https://foo.com"); client.login(new Credentials("denominator", "secret")); }}扩展功能
1. 基本使用
接口的定义可以是单一的接口,也可以是带继承层级的接口列表。
interface BaseAPI { @RequestLine("GET /health") String health(); @RequestLine("GET /all") List<Entity> all();}interface CustomAPI extends BaseAPI { @RequestLine("GET /custom") String custom();}我们也可以定义泛型类型
@Headers("Accept: application/json")interface BaseApi<V> { @RequestLine("GET /api/{key}") V get(@Param("key") String key); @RequestLine("GET /api") List<V> list(); @Headers("Content-Type: application/json") @RequestLine("PUT /api/{key}") void put(@Param("key") String key, V value);}interface FooApi extends BaseApi<Foo> { }interface BarApi extends BaseApi<Bar> { }2. 日志级别
Feign会根据不同的日志级别,来输出不同的日志,在Feign里面定义了4种日志级别。
/** * Controls the level of logging. */public enum Level { /** * No logging.不记录日志 */ NONE, /** * Log only the request method and URL and the response status code and execution time. * 仅仅记录请求方法、url、返回状态码及执行时间 */ BASIC, /** * Log the basic information along with request and response headers. * 在记录基本信息上,额外记录请求和返回的头信息 */ HEADERS, /** * Log the headers, body, and metadata for both requests and responses. * 记录全量的信息,包括:头信息、body信息、请求和返回的元数据等 */ FULL}使用方式如下:
public class Example { public static void main(String[] args) { GitHub github = Feign.builder() .decoder(new GsonDecoder()) .logger(new Logger.JavaLogger().appendToFile("logs/http.log")) .logLevel(Logger.Level.FULL) .target(GitHub.class, "https://api.github.com"); }}3. 请求阻拦器
我们可以通过定义一个请求阻拦器RequestInterceptor来对请求数据进行修改,比方增加一个请求头或者者校验受权信息等等。
static class ForwardedForInterceptor implements RequestInterceptor { @Override public void apply(RequestTemplate template) { template.header("X-Forwarded-For", "origin.host.com"); }}public class Example { public static void main(String[] args) { Bank bank = Feign.builder() .decoder(accountDecoder) .requestInterceptor(new ForwardedForInterceptor()) .target(Bank.class, "https://api.examplebank.com"); }}4. 动态查询参数@QueryMap
一般情况下,我们使用@QueryMap时,传入的参数为Map<String, Object>类型,如下所示:
public interface Api { @RequestLine("GET /find") V find(@QueryMap Map<String, Object> queryMap);}但有时候,为了让我们的参数定义得更清晰易懂,我们也可以使用POJO方式,如下所示。这种方式是通过反射直接获取字段名称和值的方式来实现的。假如POJO里面的某个字段为null或者者空串,将会从查询参数中移除掉(也就是不生效)。
public interface Api { @RequestLine("GET /find") V find(@QueryMap CustomPojo customPojo);}假如我们更喜欢使用getter、setter的方式来读取和设置值,那么我们可以自己设置查询参数编码器。
public class Example { public static void main(String[] args) { MyApi myApi = Feign.builder() .queryMapEncoder(new BeanQueryMapEncoder()) .target(MyApi.class, "https://api.hostname.com"); }}5. 自己设置错误解决器
Feign有默认的错误解决器,当我们想自行解决错误,也是可以的。可以通过自己设置ErrorDecoder来实现。
public class Example { public static void main(String[] args) { MyApi myApi = Feign.builder() .errorDecoder(new MyErrorDecoder()) .target(MyApi.class, "https://api.hostname.com"); }}它会捕获http返回状态码为非2xx的错误,并调用ErrorDecoder. decode()方法。我们可以抛出自己设置异常,或者者做额外的解决逻辑。假如我们想重复屡次调用,需要抛出RetryableException,并定义且注册额外的Retryer。
6. 自己设置Retry
我们可以通过实现Retryer接口的方式来自己设置重试策略。Retry会对IOException和ErrorDecoder组件抛出的RetryableException进行重试。假如达到了最大重试次数仍不成功,我们可以抛出RetryException。
自己设置Retryer的使用如下所示:
public class Example { public static void main(String[] args) { MyApi myApi = Feign.builder() .retryer(new MyRetryer()) .target(MyApi.class, "https://api.hostname.com"); }}7. 接口的静态方法和默认方法
在java8及以上版本,我们可以在接口里面定义静态方法和默认方法。Feign也支持这种写法,但是有特殊的作用。
- 静态方法可以写自己设置的
Feign定义 - 默认方法可以在参数中传入默认值
interface GitHub { @RequestLine("GET /repos/{owner}/{repo}/contributors") List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo); @RequestLine("GET /users/{username}/repos?sort={sort}") List<Repo> repos(@Param("username") String owner, @Param("sort") String sort); default List<Repo> repos(String owner) { return repos(owner, "full_name"); } /** * Lists all contributors for all repos owned by a user. */ default List<Contributor> contributors(String user) { MergingContributorList contributors = new MergingContributorList(); for(Repo repo : this.repos(owner)) { contributors.addAll(this.contributors(user, repo.getName())); } return contributors.mergeResult(); } static GitHub connect() { return Feign.builder() .decoder(new GsonDecoder()) .target(GitHub.class, "https://api.github.com"); }}总结
本文先简单详情了Feign,而后给出了一个入门级的例子,最后对每个功能、组件和扩展进行了补充说明。楼主相信通过这些文字,足够让我们进入Feign的大门了。
后面我们将更加深入地理解Feign,尤其是Feign的源码。
参考链接
- OpenFeign/feign
- https://www.songma.com/p/3d597e9d2d67
- https://my.oschina.net/joryqiao/blog/1925633
1. 本站所有资源来源于用户上传和网络,如有侵权请邮件联系站长!
2. 分享目的仅供大家学习和交流,您必须在下载后24小时内删除!
3. 不得使用于非法商业用途,不得违反国家法律。否则后果自负!
4. 本站提供的源码、模板、插件等等其他资源,都不包含技术服务请大家谅解!
5. 如有链接无法下载、失效或广告,请联系管理员处理!
6. 本站资源售价只是摆设,本站源码仅提供给会员学习使用!
7. 如遇到加密压缩包,请使用360解压,如遇到无法解压的请联系管理员
开心源码网 » 深入了解feign(01)-使用入门