聊聊springboot项目如何细粒度控制API响应值

前言

不知道大家日常开发会不会有类似这样的需求，同个API接口不同版本需要返回不同响应值，不同角色需要看到不同响应数据。接到类似这样的需求，一般人的做法可能是针对不同的场景定义不同的DTO，今天给大家介绍一款在springboot项目中可以细粒度控制响应值的大杀器@JsonView

什么是@JsonView？

@JsonView是Spring MVC中使用的Jackson注解，用于在序列化和反序列化过程中控制JSON对象的特定字段。例如，该注释可以允许基于上下文仅返回对象的某些字段。

@JsonView应用场景

API版本控制：当你的API需要支持多个版本，且不同版本间返回的数据结构有所差异时，可以使用@JsonView来区分不同版本间的JSON输出。为每个API版本定义一个对应的视图接口（如V1View、V2View等），并在对象属性上标注相应的视图。在API控制器方法中，根据请求的版本信息指定要使用的视图，确保返回的JSON只包含该版本所需的属性。
权限控制：在实现基于角色的访问控制（RBAC）的系统中，不同用户角色可能对同一资源有不同的访问权限。例如，普通用户只能查看某条记录的基本信息，而管理员可以查看所有详情。通过定义诸如PublicView、AdminView等视图，并在属性上标注对应权限，可以在序列化时根据当前登录用户的权限级别决定返回哪些属性。
性能优化：在某些情况下，返回给客户端的JSON数据可能包含大量属性，其中部分属性的计算或获取成本较高。为了提高响应速度，可以为这些昂贵属性定义一个特定的视图（如DetailedView），并在默认情况下仅返回基础数据。当客户端明确请求详细信息时，才启用包含这些属性的视图。
敏感信息过滤：对于包含敏感信息（如密码、密钥、个人隐私数据等）的对象，通常不希望在公开的API响应中包含这些属性。使用@JsonView，可以创建一个不含敏感属性的视图（如PublicSafeView），确保在常规请求中不会泄露敏感信息。只有在安全的上下文中（如内部服务调用或经过特殊身份验证的请求），才使用包含敏感属性的视图。
前端定制化：在构建复杂的单页面应用程序（SPA）时，前端可能需要从后端获取同一种资源的不同“视图”。例如，列表视图可能只需要对象的ID和标题，而详情视图则需要完整的属性集。通过在后端API中使用@JsonView，前端可以根据当前界面的需求发起带有特定视图标识的请求，从而减少不必要的网络带宽消耗和前端处理负担。
测试与调试：在开发和调试阶段，有时需要快速查看对象的全部属性，或者专注于特定属性的值。@JsonView可以方便地切换JSON输出的内容，有助于开发者在不同场景下更高效地分析数据。

示例

示例一：在控制器的方法配置@JsonView并绑定视图规则

注：本示例以springboot web项目来演示，因为springboot的web包本身就含有Jackson包，因此无需引入其他jar

1、定义视图规则接口

public interface AdminJsonView extends PrivateJsonView {
}
public interface UserJsonView extends ProtectedJsonView {
}
public interface PublicJsonView {
}

注：上述的AdminJsonView、UserJsonView、PrivateJsonView、ProtectedJsonView均继承PublicJsonView，具体可以查看下方demo链接代码

2、定义需要渲染的视图model

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class User {

    @JsonView(PublicJsonView.class)
    private String username;

    @JsonView(PublicJsonView.class)
    private String fullname;

    @JsonView(PublicJsonView.class)
    private Integer age;

    @JsonView({UserJsonView.class,AdminJsonView.class})
    private String email;

    @JsonView(AdminJsonView.class)
    private String phone;

    @JsonView(PublicJsonView.class)
    private Address address;



}

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Address {

    @JsonView({UserJsonView.class, AdminJsonView.class})
    private String streetName;

    @JsonView(PublicJsonView.class)
    private String city;

    @JsonView(PublicJsonView.class)
    private String country;

    @JsonView(AdminJsonView.class)
    private String fullAddress;
}

3、定义演示controller

@RestController
@RequestMapping("user")
@RequiredArgsConstructor
public class UserController {


    @GetMapping("public")
    @JsonView(PublicJsonView.class)
    public User publicUser(){
        return UserUtil.generateUser();
    }

    @GetMapping("default")
    @JsonView(UserJsonView.class)
    public User defaultUser(){
        return UserUtil.generateUser();
    }

    @GetMapping("admin")
    @JsonView(AdminJsonView.class)
    public User adminUser(){
        return UserUtil.generateUser();
    }
}

在每个方法上用@JsonView指定返回对象时使用哪个视图User，然后对3个方法进行测试，通过浏览器访问

1、publicJsonView场景

ed3c7a38298bbe17c76afd6c014791a5_f592f0a154256a915248b69adfaa17e6.png

2、userJsonView场景

cf5faa818ba4e1d70e5c5b1bc6c933bb_0475612dc4c78a5ebe06b7d67ea606e3.png

3、adminJsonView场景

0a9849ce717cf4d875ce5c17d0728ada_c443bbbbb677592054339a6186202789.png

通过浏览器访问的结果，可以看到不同的视图返回不同的响应值。

因为每个控制器方法只能指定一个@Jsonview注解，因此上述的示例比较适用于API不同版本响应不同值的场景，如果我们想通过一个方法就可以控制不同的响应值输出，我们就可以采用示例二的做法

示例二：通过MappingJacksonValue来控制视图

示例以不同token响应不同视图为例

1、编写维系token与jsonview视图规则的映射绑定

public class UserJsonViewFactory implements JsonViewFactory {

    private Map<String,Class<? extends PublicJsonView>> jsonViewClassMap = new ConcurrentHashMap<>();
    @Override
    public Class<? extends PublicJsonView> getJsonViewClass(HttpServletRequest request,Object... body) {
        String token = request.getHeader("token");
        if(StringUtils.isEmpty(token)){
            return null;
        }
        return jsonViewClassMap.get(token);
    }

    @Override
    public void initJsonViewClasses() {
        jsonViewClassMap.put("123", PublicJsonView.class);
        jsonViewClassMap.put("456", UserJsonView.class);
        jsonViewClassMap.put("789", AdminJsonView.class);
    }
}

2、编写控制器

@RestController
@RequestMapping("user")
@RequiredArgsConstructor
public class UserController {

    private final UserJsonViewFactory userJsonViewFactory;

    

    @GetMapping("getUserByToken")
    public MappingJacksonValue getUserByToken(HttpServletRequest request){
        MappingJacksonValue mappingJacksonValue = new MappingJacksonValue(UserUtil.generateUser());
        Class<? extends PublicJsonView> roleViewByToken = userJsonViewFactory.getJsonViewClass(request);
        if(roleViewByToken != null){
            mappingJacksonValue.setSerializationView(roleViewByToken);
        }

        return mappingJacksonValue;

    }

   
}

3、测试不同token的响应值情况

[root@master01 ~]# curl http://localhost:8080/user/getUserByToken -H 'token:123'
{"username":"hanzhize","fullname":"韩志泽","age":23,"address":{"city":"汕头","country":"Senegal"}}

[root@master01 ~]# curl http://localhost:8080/user/getUserByToken -H 'token:456'
{"username":"luzhehan","fullname":"卢哲瀚","age":25,"email":"luzhehan@qq.com","address":{"streetName":"韩路","city":"汕尾","country":"Macao"}}

[root@master01  ~]# curl http://localhost:8080/user/getUserByToken -H 'token:789'
{"username":"denghao","fullname":"邓浩","age":2,"email":"denghao@qq.com","phone":"334-44107556","address":{"streetName":"张街","city":"库尔勒","country":"Congo","fullAddress":"Suite 236 龚桥3号, 张家口, 豫 196243"}}

通过测试可以发现不同的token返回不同的响应值，虽然上述实现通过一个方法就可以控制不同的响应值输出，但是实际开发过程中，如果我们是一个已经在运行的项目，业务对象比较多，把原有的业务对象改成mappingJacksonValue，这样改的成本就有点高。因此还有没有更优雅的方式，接下来就看下示例三的做法

示例三：通过ResponseBodyAdvice+objectMapper实现

示例仍然以不同token响应不同视图为例，维系token与jsonview视图规则的映射绑定同示例二

1、编写ResponseBodyAdvice

@RestControllerAdvice
@Slf4j
public class JsonViewReponseBodyAdvice implements ResponseBodyAdvice<Object>, ApplicationContextAware {

    private final ObjectMapper objectMapper;

    private final JsonViewProperty jsonViewProperty;

    private ApplicationContext applicationContext;

    public JsonViewReponseBodyAdvice(JsonViewProperty jsonViewProperty) {
        this.jsonViewProperty = jsonViewProperty;
        objectMapper = new ObjectMapper();

    }
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        if(!jsonViewProperty.isEnabled() || returnType.hasMethodAnnotation(JsonView.class) || CollectionUtils.isEmpty(jsonViewProperty.getJsonViewModelClasses())){
            return false;
        }

        return isMatchJsonViewModel(Objects.requireNonNull(returnType.getMethod()).getReturnType());

    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        if(body == null){
            return null;
        }
        Class<? extends PublicJsonView> jsonViewClass = getJsonViewClass(body,request);

        try {
            if(jsonViewClass != null){
                objectMapper.setConfig(objectMapper.getSerializationConfig().withView(jsonViewClass));
            }
            String json = objectMapper.writeValueAsString(body);
            return objectMapper.readValue(json,body.getClass());
        } catch (Exception e) {
            log.error("json序列化异常",e);
        }finally {
            // 重置ObjectMapper的JsonView配置
            objectMapper.setConfig(objectMapper.getSerializationConfig().withView(null));
        }
        return body;
    }

    private Class<? extends PublicJsonView> getJsonViewClass(Object body,ServerHttpRequest request) {
        if(body == null || !isMatchJsonViewModel(body.getClass())){
            return null;
        }

        JsonViewFactory jsonViewFactory = getJsonViewFactory(body);

        ServletServerHttpRequest servletServerHttpRequest = (ServletServerHttpRequest) request;

        return jsonViewFactory.getJsonViewClass(servletServerHttpRequest.getServletRequest(),body);


    }

    private JsonViewFactory getJsonViewFactory(Object body){
        if(body == null){
            return null;
        }

        return applicationContext.getBean(body.getClass().getName() + JSON_VIEW_FACTORY_SUFFIX,JsonViewFactory.class);

    }


    private boolean isMatchJsonViewModel(Class<?> modelClz){
        return jsonViewProperty.getJsonViewModelClasses().stream().anyMatch(clazz -> clazz.equals(modelClz));
    }

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.applicationContext = applicationContext;
    }
}

2、编写controller

@RestController
@RequestMapping("user")
public class UserController {

    @GetMapping("/get")
    public User getUser(){
        return UserUtil.generateUser();
    }
}

3、在application.yml做如下配置

lybgeek:
  jsonview:
    enabled: true
    ignore-null-property-value: true
    json-view-factory-map:
      com.github.lybgeek.jsonview.user.model.User: com.github.lybgeek.jsonview.user.roleview.factory.UserJsonViewFactory

注： json-view-factory-map主要是用来维系视图对象bean和生产视图规则工厂的绑定

3、测试不同token的响应值情况

[root@master01 ~]# curl http://localhost:8080/user/get -H 'token:123'
{"username":"zhengminghui","fullname":"郑明辉","age":0,"address":{"city":"唐山","country":"Ghana"}}

[root@master01 ~]# curl http://localhost:8080/user/get -H 'token:456'
{"username":"fengyuze","fullname":"冯雨泽","age":0,"email":"fengyuze@qq.com","address":{"streetName":"贺侬","city":"阳泉","country":"Faroe Islands"}}

[root@master01 ~]# curl http://localhost:8080/user/get -H 'token:789'
{"username":"lu:jinpeng","fullname":"吕晋鹏","age":20,"email":"lu:jinpeng@qq.com","phone":"48000096798","address":{"streetName":"姚路","city":"德州","country":"Colombia","fullAddress":"孙侬95号, 潍坊, 澳 406722"}

通过测试可以发现不同token其响应的视图也是不一样的

总结

@JsonView主要应用于需要根据业务逻辑、安全要求、性能考虑或API设计原则动态调整JSON输出内容的场景，帮助开发者精确控制序列化过程，实现数据暴露的灵活性和安全性。不过这边有几点注意事项

@JsonView不处理持久层上的过滤，而只处理视图层上的过滤。这意味着它不会减少数据库的负载；从数据库中获取完整的对象，但只有部分对象被序列化并发送给客户端。
默认情况下，@JsonView 不适用于子对象。如果有嵌套对象并且想要将 @JsonView 应用于它们，则需要手动将 @JsonView 注释添加到子对象的每个字段。

最后Jackson有个@JsonFilter注解也可以实现上述效果，不过它与@JsonView 有所不同，主要适用于更复杂、动态的过滤场景，特别是在需要对对象树中的多个嵌套层级或集合元素进行条件筛选。感兴趣的朋友可以去了解下

demo链接

https://github.com/lyb-geek/springboot-learning/tree/master/springboot-jsonview

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 206,723评论 6赞 481
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 88,485评论 2赞 382
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 152,998评论 0赞 344
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 55,323评论 1赞 279
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 64,355评论 5赞 374
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 49,079评论 1赞 285
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 38,389评论 3赞 400
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 37,019评论 0赞 259
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 43,519评论 1赞 300
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 35,971评论 2赞 325
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 38,100评论 1赞 333
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 33,738评论 4赞 324
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 39,293评论 3赞 307
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 30,289评论 0赞 19
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 31,517评论 1赞 262
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 45,547评论 2赞 354
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 42,834评论 2赞 345

聊聊springboot项目如何细粒度控制API响应值

前言

示例

示例一：在控制器的方法配置@JsonView并绑定视图规则

示例二：通过MappingJacksonValue来控制视图

示例三：通过ResponseBodyAdvice+objectMapper实现

总结

demo链接

推荐阅读更多精彩内容