返回值解析

返回值解析指将Controller返回值写入到AsyncResponse中的过程（包含序列化）
Tags:

返回值解析逻辑

Restlight默认支持的返回值解析方式包括

  • @ResponseBody
  • @ResponseStatus
  • 普通类型(String, byte[], int 等)

与参数解析类似， 每个功能都对应了一个返回值解析器的实现。

接口定义

public interface ReturnValueResolver {

    /**
     * 解析出对应返回值为byte[]
     */
    byte[] resolve(Object returnValue,
                   AsyncRequest request,
                   AsyncReponse response) throws Exception;

}

框架会在启动的初始化阶段试图为每一个Controller中的每一个参数都找到一个与之匹配的ReturnValueResolver用于响应的返回值解析。

框架如何确定ReturnValueResolver

ReturnValueResolverAdapter


public interface ReturnValueResolverPredicate {

    /**
     * 判断当前ReturnValueResolver是否支持给定InvocableMethod解析
     * 每一个Controller都对应一个InvocableMethod实例， 
     * 可以通过InvocableMethod获取注解, 返回值类型等各类反射相关的元数据信息
     */
    boolean supports(InvocableMethod invocableMethod);

}

public interface ReturnValueResolverAdapter extends ReturnValueResolverPredicate, ReturnValueResolver, Ordered {

    @Override
    default int getOrder() {
        return HIGHEST_PRECEDENCE;
    }

}

初始化逻辑：

  1. 按照getOrder()方法的返回将Srping容器中所有的ReturnValueResolverAdapter进行排序
  2. 按照排序后的顺序依次调用supports(InvocableMethod invocableMethod)方法， 返回true则将其作为该参数的ReturnValueResolver， 运行时每次请求都将调用resolve(Object returnValue, AsyncRequest request, AsyncReponse response)方法进行参数解析， 并且运行时不会改变。
  3. 未找到则启动报错。

细心的人可能会发现该设计可能并不能覆盖到以下场景

  • 因为resolve(Object returnValue, AsyncRequest request, AsyncReponse response)方法参数中并没有传递InvocableMethod参数， 虽然初始化阶段能根据supports(InvocableMethod invocableMethod)方法获取Controller方法元数据信息（获取某个注解， 获取参数类型等等）判断是否支持， 但是如果运行时也需要获取Controller方法的元数据信息（某个注解的值等）的话，此接口则无法满足需求。
  • 假如ReturnValueResolverAdapter实现中需要做序列化操作， 因此期望获取到Spring容器中的序列化器时，则该接口无法支持（例如@ResponseBody的场景）。

针对以上问题， 答案是确实无法支持。因为Restlight的设计理念是

  • 能在初始化阶段解决的问题就在初始化阶段解决

因此不期望用户以及Restlight的开发人员大量的在运行时去频繁获取一些JVM启动后就不会变动的内容(如： 注解的值)， 甚至针对某些元数据信息使用ConcurrentHashMap进行缓存（看似是为了提高性能的缓存， 实际上初始化就固定了的内容反而增加了并发性能的损耗）。

基于以上原因我们提供了另一个ReturnValueResolver的实现方式

ReturnValueResolverFactory

public interface ReturnValueResolverFactory extends ReturnValueResolverPredicate, Ordered {

    ReturnValueResolver createResolver(InvocableMethod invocableMethod,
                                    List<? extends HttpResponseSerializer> serializers);

    @Override
    default int getOrder() {
        return HIGHEST_PRECEDENCE;
    }
}

与上面的ReturnValueResolver类似

初始化逻辑：

  1. 按照getOrder()方法的返回将所有的ReturnValueResolverFactory进行排序
  2. 按照排序后的顺序依次调用supports(InvocableMethod invocableMethod)方法， 返回true则将其作为该参数的ReturnValueResolverFactory， 同时调用createResolver(InvocableMethod invocableMethod, List<? extends HttpResponseSerializer> serializers)方法创建出对应的ReturnValueResolver
  3. 未找到则启动报错。

由于初始化时通过createResolver(InvocableMethod invocableMethod, List<? extends HttpResponseSerializer> serializers)方法传入了InvocableMethod以及序列化器， 因此能满足上面的要求。

两种模式的定位

  • ReturnValueResolver： 适用于解析器不依赖方法元数据信息以及序列化的场景。例如： 如果Controller方法上上使用了@XXX注解则返回某个固定的值。
  • ReturnValueResolverFactory： 适用于解析器依赖方法元数据信息以及序列化的场景。例如： @ResponseBody， @ResponseStatus(reason = “error”)。

自定义返回值解析器

将自定义实现的ReturnValueResolverAdapter或者ReturnValueResolverFactory注入到Spring容器即可。

  • ReturnValueResolverAdapter案例

场景： 当Controller方法上有@AppId注解时， 返回固定的AppId

// 自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AppId {
}

@Bean
public ReturnValueResolverAdapter resolver() {

    private static byte[] APP_ID = "your appid".getBytes(StandardCharsets.UTF_8);

    return new ReturnValueResolverAdapter() {
        @Override
        public boolean supports(InvocableMethod invoicableMethod) {
            // 当方法上有此注解时生效
            return invoicableMethod.hasMethodAnnotation(AppId.class);
        }
 
        @Override
        public byte[] resolve(Object returnValue,
                   AsyncRequest request,
                   AsyncReponse response) {
            return APP_ID;
        }
    };
}

controller使用


@GetMapping("/foo")
@AppId
public String foo() {
    return "";
}

上面的代码自定义实现了依据自定义注解获取固定appId的功能

  • ReturnValueResolverFactory

场景： 通过自定义注解对所有String类型的返回值加上一个指定前缀。

// 自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Suffix {
    String value();
}

@Bean
    public ReturnValueResolverFactory resolver() {
        return new ReturnValueResolverFactory() {
            @Override
            public boolean supports(InvocableMethod invocableMethod) {
                // 当方法上有此注解时生效
                return String.class.equals(invocableMethod.getMethod().getReturnType()) && parameter.hasMethodAnnotation(CustomHeader.class);
            }
            
            public ReturnValueResolver createResolver(InvocableMethod invocableMethod,
                                                      List<? extends HttpResponseSerializer> serializers) {
                return new Resovler(invocableMethod);
            }
            
        };
    }

    /**
     * 实际ArgumentResolver实现
     */
    private static class Resolver implements ReturnValueResolver {

        private final String suffix;

        private Resolver(InvocableMethod invocableMethod) {
            // 获取前缀
            Suffix anno = invocableMethod.getMethodAnnotation(Suffix.class);
            this.suffix = anno.value();
        }

        @Override
        public byte[] resolve(Object returnValue,
                   AsyncRequest request,
                   AsyncReponse response) {
            // 拼接
            return suffix + String.valueOf(returnValue);
        }
    }

controller使用


@GetMapping("/foo")
@Suffix
public String foo() {
    return "foo";
}

Last modified March 10, 2022: introduce docsy as the website framework and add docs-v1.0.0 (#120) (79630ff)