Spring Boot+原生注解@JsonView 輕松過濾字段，真的優(yōu)雅！

作者：儒猿團(tuán)隊 2025-07-14 02:00:00

@JsonView 是 Jackson 庫提供的一個注解，Spring Boot 對它有原生支持。簡單來說，它就像一個 “數(shù)據(jù)篩子”，可以在序列化（把 Java 對象轉(zhuǎn)成 JSON）時，根據(jù)不同的場景決定哪些字段要展示，哪些要隱藏。

兄弟們，今天咱們來聊聊 Spring Boot 里一個堪稱 “數(shù)據(jù)化妝師” 的神器 ——@JsonView。想象一下，你開發(fā)了一個接口，前端說：“我只要用戶的姓名和郵箱，別給我密碼和身份證號！” 這時候，你是不是習(xí)慣性地想寫一堆 DTO？或者用 @JsonIgnore 一頓亂標(biāo)？別急，@JsonView 能讓你用更優(yōu)雅的姿勢解決這個問題。

一、@JsonView 是什么？能吃嗎？

@JsonView 是 Jackson 庫提供的一個注解，Spring Boot 對它有原生支持。簡單來說，它就像一個 “數(shù)據(jù)篩子”，可以在序列化（把 Java 對象轉(zhuǎn)成 JSON）時，根據(jù)不同的場景決定哪些字段要展示，哪些要隱藏。比如：

用戶注冊接口：只返回用戶名和郵箱。
用戶詳情接口：返回所有字段，包括地址和手機(jī)號。
管理員接口：甚至可以返回敏感信息（但記得加密哦！）。

它的核心思想是視圖（View）。你可以定義多個視圖接口，每個接口代表一種數(shù)據(jù)展示規(guī)則。然后在實體類的字段上標(biāo)注這些視圖，最后在控制器方法里指定用哪個視圖。就這么簡單！

二、入門案例：給用戶數(shù)據(jù)化個淡妝

咱們先來看一個簡單的例子。假設(shè)我們有一個 User 類：

public class User {
    @JsonView(User.BaseView.class)
    private Long id;
    @JsonView(User.BaseView.class)
    private String username;
    @JsonView(User.DetailView.class)
    private String email;
    @JsonView(User.AdminView.class)
    private String password;
    // 視圖接口定義
    public interface BaseView {}
    public interface DetailView extends BaseView {}
    public interface AdminView extends DetailView {}
}

這里定義了三個視圖：

BaseView：基礎(chǔ)信息，包含 id 和 username。
DetailView：繼承自 BaseView，額外包含 email。
AdminView：繼承自 DetailView，額外包含 password。

接下來，在控制器里指定視圖：

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    @JsonView(User.BaseView.class)
    public User getUser(@PathVariable Long id) {
        // 假設(shè)這里從數(shù)據(jù)庫查詢用戶
        return userService.findById(id);
    }
    @GetMapping("/detail/{id}")
    @JsonView(User.DetailView.class)
    public User getDetailUser(@PathVariable Long id) {
        return userService.findById(id);
    }
    @GetMapping("/admin/{id}")
    @JsonView(User.AdminView.class)
    public User getAdminUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

這樣，三個接口就會返回不同的字段：

/users/1：返回{"id":1, "username":"張三"}。
/users/detail/1：返回{"id":1, "username":"張三", "email":"zhangsan@example.com"}。
/users/admin/1：返回所有字段，包括password（但實際項目中記得加密！）。

是不是比寫三個 DTO 清爽多了？而且視圖接口可以無限繼承，靈活組合。比如，如果某個接口需要同時展示 BaseView 和 DetailView 的字段，你可以再定義一個復(fù)合視圖：

public interface CompositeView extends BaseView, DetailView {}

然后在控制器方法上用@JsonView(CompositeView.class)，就這么簡單！

三、進(jìn)階玩法：處理關(guān)聯(lián)對象的千層餅

實際項目中，對象往往不是孤立的。比如，一個 User 可能關(guān)聯(lián)一個 Order，Order 又關(guān)聯(lián)一個 Product。這時候，@JsonView 的嵌套處理就顯得尤為重要。

3.1 簡單關(guān)聯(lián)：返回空殼對象

假設(shè) User 有一個 Order 字段：

public class User {
    // ...其他字段
    @JsonView(User.OrderView.class)
    private Order order;
    public interface OrderView {}
}
public class Order {
    @JsonView(Order.BaseView.class)
    private Long id;
    @JsonView(Order.DetailView.class)
    private Date createTime;
    public interface BaseView {}
    public interface DetailView extends BaseView {}
}

如果在控制器中使用@JsonView(User.OrderView.class)，返回的 JSON 會是：

{
    "id": 1,
    "username": "張三",
    "order": {}
}

注意，這里的 order 是一個空對象。因為 User 的 OrderView 只標(biāo)記了 order 字段本身，而 Order 類的字段沒有被當(dāng)前視圖覆蓋。這時候，Jackson 會默認(rèn)返回空對象，而不是遞歸序列化所有字段。

3.2 深度關(guān)聯(lián)：繼承視圖解千層

如果我們希望返回 Order 的 id 和 createTime，該怎么辦呢？很簡單，讓 User 的 OrderView 繼承 Order 的 BaseView：

public class User {
    // ...其他字段
    @JsonView(User.OrderView.class)
    private Order order;
    public interface OrderView extends Order.BaseView {}
}
public class Order {
    @JsonView(Order.BaseView.class)
    private Long id;
    @JsonView(Order.DetailView.class)
    private Date createTime;
    public interface BaseView {}
    public interface DetailView extends BaseView {}
}

然后在控制器中使用@JsonView(User.OrderView.class)，返回的 JSON 就會是：

{
    "id": 1,
    "username": "張三",
    "order": {
        "id": 1001,
        "createTime": "2023-10-01T12:00:00"
    }
}

這里的關(guān)鍵是視圖繼承。User.OrderView 繼承了 Order.BaseView，所以 Jackson 在序列化 order 字段時，會應(yīng)用 Order.BaseView 的規(guī)則，即包含 id 字段。如果還需要 createTime，可以讓 User.OrderView 繼承 Order.DetailView：

public interface OrderView extends Order.DetailView {}

這樣，返回的 JSON 就會包含 createTime 字段。

3.3 多層嵌套：鏈?zhǔn)嚼^承無壓力

如果 Order 還關(guān)聯(lián)了 Product，Product 又關(guān)聯(lián)了 Category，該怎么辦呢？別慌，繼續(xù)用繼承：

public class Order {
    // ...其他字段

    @JsonView(Order.ProductView.class)
    private Product product;

    publicinterface ProductView extends Product.BaseView {}
}

publicclass Product {
    @JsonView(Product.BaseView.class)
    private Long id;

    @JsonView(Product.DetailView.class)
    private String name;

    @JsonView(Product.CategoryView.class)
    private Category category;

    publicinterface BaseView {}
    publicinterface DetailView extends BaseView {}
    publicinterface CategoryView extends Category.BaseView {}
}

publicclass Category {
    @JsonView(Category.BaseView.class)
    private Long id;

    @JsonView(Category.DetailView.class)
    private String name;

    publicinterface BaseView {}
    publicinterface DetailView extends BaseView {}
}

然后在控制器中使用@JsonView(User.OrderView.class)，其中 User.OrderView 繼承了 Order.ProductView，而 Order.ProductView 又繼承了 Product.CategoryView，最終會返回：

{
    "id": 1,
    "username": "張三",
    "order": {
        "id": 1001,
        "createTime": "2023-10-01T12:00:00",
        "product": {
            "id": 2001,
            "category": {
                "id": 3001
            }
        }
    }
}

這樣，通過層層繼承，我們可以靈活控制任意深度的嵌套對象序列化。

四、動態(tài)視圖：讓數(shù)據(jù)展示更靈活

前面的例子都是在控制器方法上用 @JsonView 注解指定視圖，這種方式適合固定場景。但如果我們需要根據(jù)用戶角色、請求參數(shù)等動態(tài)決定視圖，該怎么辦呢？這時候，可以使用MappingJacksonValue類。

4.1 基于用戶角色的動態(tài)視圖

假設(shè)我們有一個接口，普通用戶只能看到 BaseView，管理員可以看到 AdminView。我們可以這樣做：

@GetMapping("/dynamic/{id}")
public MappingJacksonValue getDynamicUser(@PathVariable Long id) {
    User user = userService.findById(id);
    MappingJacksonValue mapping = new MappingJacksonValue(user);

    // 獲取當(dāng)前用戶角色
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
    if (authentication != null && authentication.getAuthorities().contains(new SimpleGrantedAuthority("ROLE_ADMIN"))) {
        mapping.setSerializationView(User.AdminView.class);
    } else {
        mapping.setSerializationView(User.BaseView.class);
    }

    return mapping;
}

這樣，管理員訪問時會返回所有字段，普通用戶只能看到基礎(chǔ)信息。

4.2 基于請求參數(shù)的動態(tài)視圖

如果希望根據(jù)請求參數(shù)（如?view=detail）來決定視圖，可以這樣做：

@GetMapping("/dynamic/{id}")
public MappingJacksonValue getDynamicUser(@PathVariable Long id, @RequestParam(defaultValue = "base") String view) {
    User user = userService.findById(id);
    MappingJacksonValue mapping = new MappingJacksonValue(user);

    switch (view) {
        case"detail":
            mapping.setSerializationView(User.DetailView.class);
            break;
        case"admin":
            mapping.setSerializationView(User.AdminView.class);
            break;
        default:
            mapping.setSerializationView(User.BaseView.class);
    }

    return mapping;
}

這樣，前端可以通過參數(shù)靈活選擇需要的視圖。

五、性能優(yōu)化：別讓 @JsonView 拖后腿

雖然 @JsonView 很方便，但如果使用不當(dāng)，可能會影響性能。比如，當(dāng)處理大量數(shù)據(jù)時，頻繁的反射和視圖解析可能會帶來額外開銷。不過，通過合理設(shè)計，我們可以將性能影響降到最低。

5.1 避免過度使用視圖繼承

視圖繼承雖然靈活，但如果嵌套層次過深，可能會導(dǎo)致 Jackson 在序列化時進(jìn)行大量的類檢查。建議將視圖繼承控制在合理范圍內(nèi)，或者使用復(fù)合視圖代替多層繼承。

5.2 緩存視圖信息

在高并發(fā)場景下，可以考慮緩存視圖信息。例如，將視圖類和字段的映射關(guān)系緩存到 ConcurrentHashMap 中，避免每次序列化都反射解析字段。

5.3 與 DTO 結(jié)合使用

對于極其復(fù)雜的場景，@JsonView 可能會讓實體類變得臃腫。這時候，可以結(jié)合 DTO 使用：用 @JsonView 處理簡單場景，用 DTO 處理復(fù)雜的數(shù)據(jù)轉(zhuǎn)換。這樣既能保持代碼簡潔，又能提升性能。

六、常見問題及解決方案

6.1 關(guān)聯(lián)對象返回空殼

問題：當(dāng)使用 @JsonView 處理關(guān)聯(lián)對象時，返回的是一個空對象，而不是期望的字段。

解決方案：確保關(guān)聯(lián)對象的字段被當(dāng)前視圖覆蓋。可以通過視圖繼承或直接在關(guān)聯(lián)對象的字段上標(biāo)注當(dāng)前視圖。

6.2 視圖接口無法繼承

問題：在 Java 8 中，接口不能有默認(rèn)方法，導(dǎo)致視圖繼承時無法共享公共字段。

解決方案：使用標(biāo)記接口，或者在父視圖中定義公共字段，子視圖繼承父視圖。

6.3 與 @JsonIgnore 沖突

問題：當(dāng)字段同時被 @JsonView 和 @JsonIgnore 標(biāo)注時，@JsonView 會被忽略。

解決方案：@JsonIgnore 的優(yōu)先級高于 @JsonView。如果需要同時使用，建議在視圖中排除該字段，而不是使用 @JsonIgnore。

6.4 包裝返回結(jié)果失效

問題：當(dāng)使用統(tǒng)一的 Result 包裝類返回數(shù)據(jù)時，@JsonView 無法過濾字段。

解決方案：在 Result 類中也應(yīng)用 @JsonView，并確保視圖接口正確繼承。或者，使用 ResponseBodyAdvice 攔截響應(yīng)，動態(tài)設(shè)置視圖。

七、與其他注解的對比

7.1 @JsonView vs @JsonIgnore

@JsonIgnore：簡單直接，但只能靜態(tài)排除字段，無法根據(jù)場景動態(tài)調(diào)整。
@JsonView：靈活強大，可以動態(tài)控制字段展示，但需要定義視圖接口。

結(jié)論：如果需要動態(tài)控制字段，優(yōu)先使用 @JsonView；如果是靜態(tài)排除，@JsonIgnore 更簡單。

7.2 @JsonView vs DTO

DTO：清晰直觀，適合復(fù)雜數(shù)據(jù)轉(zhuǎn)換，但會增加類的數(shù)量。
@JsonView：減少類的數(shù)量，保持實體類簡潔，但可能使代碼邏輯分散。

結(jié)論：簡單場景用 @JsonView，復(fù)雜場景用 DTO，或者兩者結(jié)合。

八、最佳實踐

視圖命名規(guī)范：視圖接口名稱應(yīng)與業(yè)務(wù)場景一致，如 User.BaseView、Order.DetailView。
繼承深度控制：避免超過三層繼承，必要時使用復(fù)合視圖。
敏感數(shù)據(jù)處理：敏感字段（如密碼）應(yīng)單獨放在 AdminView 中，并結(jié)合加密處理。
文檔說明：在代碼注釋中說明每個視圖的用途，方便團(tuán)隊成員理解。
單元測試：對每個視圖接口編寫測試用例，確保返回字段符合預(yù)期。

九、總結(jié)

@JsonView 是 Spring Boot 中一個被低估的神器，它讓我們可以用更優(yōu)雅的方式控制 JSON 序列化，避免了大量冗余的 DTO 和注解。通過合理設(shè)計視圖接口，結(jié)合動態(tài)視圖和性能優(yōu)化，我們可以在保證代碼簡潔的同時，滿足各種復(fù)雜的業(yè)務(wù)需求。

下次遇到 “這個接口需要返回某些字段，那個接口不需要” 的需求時，別再寫 DTO 了，試試 @JsonView 吧！它真的能讓你的代碼更優(yōu)雅，更有逼格。

雖然 @JsonView 很強大，但也別濫用。對于極其復(fù)雜的場景，還是要結(jié)合其他工具（如 MapStruct）來處理。技術(shù)沒有銀彈，合適的才是最好的。

責(zé)任編輯：武曉燕來源：石杉的架構(gòu)筆記