基于注解与反射的Java对象格式化输出工具实战

之前做后台接口日志和报表导出时，经常被 Java 对象的字段输出问题折腾：字段顺序不稳定、敏感字段要脱敏、日志里打印对象全是toString()的默认样式、接口返回字段名还得手动拼 Map。后来我在内部项目里封装了一个基于注解和反射的轻量工具，叫 Java Styler。本文就以“布吉岛·鸟鸟岛”项目里这套 styler 的实现为例，完整拆解它的设计思路、核心代码、进阶写法与常见坑点，适合对 Java 反射、注解、集合和 Lambda 有一定基础，但想提升代码组织能力的读者。

1. Java Styler 是什么，解决什么问题

1.1 从一段痛苦的业务代码说起

先看一个很常见的场景。假设有一个用户对象，包含 ID、姓名、手机号、身份证号、密码、登录次数、备注等字段。你需要在接口日志中打印这个对象，同时手机号、身份证号、密码不能明文出现。

很多人第一反应是手动写拼接逻辑：

StringBuilder sb = new StringBuilder(); sb.append("id=").append(user.getId()); sb.append(", name=").maskName(user.getName())); sb.append(", phone=").maskPhone(user.getPhone())); // 这里继续写很多重复代码

这样写的问题很明显：每个字段都要手工处理，字段一旦增加，日志代码就要跟着改；而且如果多个地方需要输出不同字段顺序，还要复制多份拼接代码。时间一长，项目里到处都是私有工具方法和不统一的输出格式。

1.2 Styler 的核心思想

Styler 本质是一个“对象样式化输出器”。它通过注解描述字段的展示规则，通过反射自动读取对象字段，再通过统一的处理器完成排序、别名、脱敏、忽略等操作。调用方只需要一行代码，就能把对象转换成指定样式的文本或 Map。

这个设计思路在很多场景下都适用：

• 接口日志脱敏，避免敏感信息明文落盘。
• 统一对外输出字段名，不用建一堆 DTO。
• 生成控制台可读的对象快照，替代默认toString()。
• 导出报表前，把对象字段按固定顺序整理成列表或 Map。

1.3 为什么不直接用现成 JSON 库

有人可能会问，用 Jackson、Gson 不也能控制字段顺序和脱敏吗？确实可以，但 JSON 库的主要目标是序列化和反序列化，做复杂脱敏时通常需要自定义Serializer，成本不低。而且如果只是想在日志中输出一段人类可读的文本，没必要把整个对象先转成 JSON 再解析。Styler 的定位更轻量，它不依赖任何第三方框架，只用 JDK 原生能力就能实现。

这篇文章里实现的 styler 不会覆盖所有企业级功能，但会提供一个清晰可扩展的骨架。读完之后，你可以根据自己的业务继续加字段权限控制、嵌套对象递归、国际化字段名等能力。

2. 环境准备与项目结构

2.1 开发环境说明

本文示例以常见环境为例，重点演示配置思路，具体版本请根据你的项目实际情况调整：

• JDK 8 及以上版本。
• 构建工具：Maven 3.6+ 或 Gradle 任意可用版本。
• IDE：IDEA 或 Eclipse 均可，IDEA 对反射调试更友好。
• 项目类型：普通 Java 工程即可，不需要引入 Spring 容器。

示例项目中的代码都使用 Java 标准库实现，没有额外引入第三方依赖，因此复制后可以直接运行。如果你想加单元测试，再单独引入 JUnit 5 即可。

2.2 项目目录规划

为了保持代码清晰，我把包结构按功能拆分：

com.bujidao.styler ├── annotation │ └── StyleField.java ├── enums │ └── MaskType.java ├── core │ ├── FieldProcessor.java │ ├── DefaultFieldProcessor.java │ └── Styler.java ├── model │ └── User.java └── Main.java

说明一下每个包的作用：

• annotation：存放自定义注解，用来描述字段输出规则。
• enums：存放脱敏类型等枚举。
• core：核心处理逻辑，包括反射读取字段、格式化、脱敏。
• model：业务实体类，演示 styler 的使用效果。
• Main：入口类，验证运行结果。

实际项目中，你可以把core部分抽成独立模块，model放在业务服务中。

3. 核心设计：注解、处理器、样式上下文

3.1 注解驱动：让字段自己“声明”规则

Java 注解是一种元数据机制，它本身不包含业务逻辑，但可以被反射读取。Styler 的第一个关键设计，就是用注解让字段“描述”自己该怎么被输出。

先定义StyleField注解：

package com.bujidao.styler.annotation; import com.bujidao.styler.enums.MaskType; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.FIELD) public @interface StyleField { int order() default 0; String alias() default ""; MaskType mask() default MaskType.NONE; boolean ignore() default false; }

四个属性分别表示：

• order：字段输出顺序，数字越小越靠前。
• alias：字段别名，比如 Java 属性名是idCard，对外展示时想叫“身份证号”或id_card，就可以用别名。
• mask：脱敏类型，支持手机号、身份证、姓名、密码等。
• ignore：是否忽略该字段，true表示不输出。

注解的@Retention必须设为RUNTIME，因为 styler 需要在程序运行期间通过反射读取注解信息。如果保留策略是SOURCE或CLASS，运行时是拿不到的。

3.2 脱敏类型枚举：把可扩展性做出来

脱敏是对象输出最常见的需求。为了不让脱敏逻辑散落在各个地方，我把脱敏类型定义成枚举：

package com.bujidao.styler.enums; public enum MaskType { NONE, PHONE, ID_CARD, NAME, PASSWORD }

枚举的好处是类型安全，写注解时不容易拼错字符串。后续要增加邮箱脱敏、银行卡脱敏，只需要在枚举中新增一个值，再在处理器中增加对应分支即可。

3.3 处理器接口：面向接口而不是面向实现

为了让 styler 更灵活，核心处理器使用接口抽象：

package com.bujidao.styler.core; import com.bujidao.styler.enums.MaskType; @FunctionalInterface public interface FieldProcessor { Object process(Object value, MaskType maskType); }

这里把它声明成@FunctionalInterface，是为了让调用方可以使用 Lambda 表达式快速实现自定义处理规则。默认处理器实现如下：

package com.bujidao.styler.core; import com.bujidao.styler.enums.MaskType; public class DefaultFieldProcessor implements FieldProcessor { @Override public Object process(Object value, MaskType maskType) { if (value == null) { return null; } if (maskType == null) { return value; } switch (maskType) { case PHONE: return maskPhone(value.toString()); case ID_CARD: return maskIdCard(value.toString()); case NAME: return maskName(value.toString()); case PASSWORD: return "******"; default: return value; } } private String maskPhone(String phone) { if (phone == null || phone.length() < 7) { return phone; } return phone.substring(0, 3) + "****" + phone.substring(phone.length() - 4); } private String maskIdCard(String idCard) { if (idCard == null || idCard.length() < 8) { return idCard; } return idCard.substring(0, 3) + "***********" + idCard.substring(idCard.length() - 4); } private String maskName(String name) { if (name == null || name.length() < 2) { return name; } return name.substring(0, 1) + "*" + name.substring(name.length() - 1); } }

手机号脱敏的规则是保留前 3 位和后 4 位；身份证保留前 3 位和后 4 位；姓名只保留第一个字和最后一个字。具体规则可以根据业务调整，这些只是示例。

4. 实现核心类：Styler

4.1 字段包装对象

反射拿到的是 Java 反射包里的Field，但排序时需要用到注解中的order值。直接拿Field和order分开管理会很散，因此我定义了一个内部字段包装对象：

package com.bujidao.styler.core; class FieldEntry { private final String name; private final Object value; private final int order; FieldEntry(String name, Object value, int order) { this.name = name; this.value = value; this.order = order; } String getName() { return name; } Object getValue() { return value; } int getOrder() { return order; } }

这样每个字段的名称、值、排序号就在同一个对象里，后面排序和渲染都很方便。

4.2 反射读取对象字段

Styler 的类名和 JDK 里已有的类没有冲突，但为了和真正的“样式框架”区分，这里把它定义为一个纯工具类。核心方法是collect，负责读取对象的所有字段：

package com.bujidao.styler.core; import com.bujidao.styler.annotation.StyleField; import com.bujidao.styler.enums.MaskType; import java.lang.reflect.Field; import java.util.ArrayList; import java.util.Comparator; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; public class Styler { private final FieldProcessor fieldProcessor; public Styler() { this(new DefaultFieldProcessor()); } public Styler(FieldProcessor fieldProcessor) { this.fieldProcessor = fieldProcessor; } private List<FieldEntry> collect(Object target) { if (target == null) { return new ArrayList<>(); } List<FieldEntry> entries = new ArrayList<>(); Field[] fields = target.getClass().getDeclaredFields(); for (Field field : fields) { StyleField styleField = field.getAnnotation(StyleField.class); if (styleField != null && styleField.ignore()) { continue; } field.setAccessible(true); Object value; try { value = field.get(target); } catch (IllegalAccessException e) { throw new IllegalStateException("读取字段失败: " + field.getName(), e); } MaskType maskType = styleField == null ? MaskType.NONE : styleField.mask(); if (maskType != MaskType.NONE && value != null) { value = fieldProcessor.process(value, maskType); } String name = field.getName(); if (styleField != null && !styleField.alias().isEmpty()) { name = styleField.alias(); } int order = styleField == null ? 0 : styleField.order(); entries.add(new FieldEntry(name, value, order)); } entries.sort(Comparator.comparingInt(FieldEntry::getOrder)); return entries; } }

这里有两个值得注意的细节。

第一，field.setAccessible(true)在 JDK 8 中通常没问题，但在 JDK 17 及以上模块化系统中，如果运行在模块化环境且没有配置--add-opens，访问私有字段可能抛出InaccessibleObjectException。普通未模块化项目不受影响，但在生产环境要注意运行参数。

第二，反射抛出的异常必须转换成明确的运行时异常，否则调用方很难快速定位是哪个字段出了问题。我在异常消息中带了字段名，排查时会方便很多。

4.3 输出为可读文本

有了collect方法，接下来就是渲染。我提供了toText和toPrettyText两种文本输出方式：

public String toText(Object target) { List<FieldEntry> entries = collect(target); StringBuilder sb = new StringBuilder(); sb.append(target.getClass().getSimpleName()).append("{"); for (int i = 0; i < entries.size(); i++) { if (i > 0) { sb.append(", "); } FieldEntry entry = entries.get(i); sb.append(entry.getName()).append("=").append(entry.getValue()); } sb.append("}"); return sb.toString(); } public String toPrettyText(Object target) { List<FieldEntry> entries = collect(target); StringBuilder sb = new StringBuilder(); sb.append(target.getClass().getSimpleName()).append(" {\n"); for (FieldEntry entry : entries) { sb.append(" ") .append(entry.getName()) .append(" = ") .append(entry.getValue()) .append("\n"); } sb.append("}"); return sb.toString(); }

toText适合单行日志，toPrettyText适合控制台或调试信息。两者共用同一套字段收集逻辑，避免了代码重复。

4.4 输出为有序 Map

在很多场景下，我们希望把对象转成有序 Map，然后交给模板引擎或报表工具处理。Java 中HashMap不保证顺序，所以这里必须使用LinkedHashMap：

public Map<String, Object> toMap(Object target) { Map<String, Object> map = new LinkedHashMap<>(); List<FieldEntry> entries = collect(target); for (FieldEntry entry : entries) { map.put(entry.getName(), entry.getValue()); } return map; }

返回有序 Map 后，你可以很方便地扩展为 JSON，也可以直接用于 Excel 导出。

5. 完整实战案例：用户信息样式输出

5.1 创建实体类 User

下面把前面写的注解用起来。在model包下创建User类：

package com.bujidao.styler.model; import com.bujidao.styler.annotation.StyleField; import com.bujidao.styler.enums.MaskType; public class User { @StyleField(order = 1, alias = "用户ID") private Long id; @StyleField(order = 2, alias = "姓名", mask = MaskType.NAME) private String name; @StyleField(order = 3, alias = "手机号", mask = MaskType.PHONE) private String phone; @StyleField(order = 4, alias = "身份证号", mask = MaskType.ID_CARD) private String idCard; @StyleField(order = 5, alias = "密码", mask = MaskType.PASSWORD) private String password; @StyleField(order = 6, alias = "登录次数") private Integer loginCount; @StyleField(order = 99, alias = "内部备注", ignore = true) private String remark; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getPhone() { return phone; } public void setPhone(String phone) { this.phone = phone; } public String getIdCard() { return idCard; } public void setIdCard(String idCard) { this.idCard = idCard; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } public Integer getLoginCount() { return loginCount; } public void setLoginCount(Integer loginCount) { this.loginCount = loginCount; } public String getRemark() { return remark; } public void setRemark(String remark) { this.remark = remark; } }

注意remark字段加了ignore = true，意味着它不会出现在 styler 的输出结果中。这个特性可以用来屏蔽内部字段或临时字段。

5.2 编写 Main 入口类

入口类放在默认包或com.bujidao.styler下都可以。为了结构清晰，我放在com.bujidao.styler包中：

package com.bujidao.styler; import com.bujidao.styler.core.Styler; import com.bujidao.styler.model.User; import java.util.Map; public class Main { public static void main(String[] args) { User user = new User(); user.setId(1001L); user.setName("张三丰"); user.setPhone("13812345678"); user.setIdCard("110101199001011234"); user.setPassword("abc123456"); user.setLoginCount(7); user.setRemark("内部员工"); Styler styler = new Styler(); System.out.println(styler.toText(user)); System.out.println(); System.out.println(styler.toPrettyText(user)); System.out.println(); Map<String, Object> userMap = styler.toMap(user); System.out.println(userMap); } }

这段代码直接运行就能看到输出效果，不需要安装任何额外依赖。

5.3 运行结果与验证

预期控制台输出如下：

User{用户ID=1001, 姓名=张*丰, 手机号=138****5678, 身份证号=110***********1234, 密码=******, 登录次数=7}

多行文本输出：

User { 用户ID = 1001 姓名 = 张*丰 手机号 = 138****5678 身份证号 = 110***********1234 密码 = ****** 登录次数 = 7 }

Map 输出：

{用户ID=1001, 姓名=张*丰, 手机号=138****5678, 身份证号=110***********1234, 密码=******, 登录次数=7}

注意字段顺序完全按照注解中的order排列，remark没有出现，敏感字段已经完成脱敏。这个结果说明 styler 已经实现了预期功能。

6. 进阶写法：结合 Lambda、Stream、动态代理

6.1 用 Lambda 自定义脱敏规则

默认处理器适合通用场景，但实际业务经常有特殊规则。比如某个字段需要前后保留两位，中间用三个星号代替。此时你可以不用修改DefaultFieldProcessor，而是在创建 styler 时传入 Lambda 表达式：

Styler customStyler = new Styler((value, maskType) -> { if (maskType == MaskType.NONE || value == null) { return value; } String str = value.toString(); if (str.length() <= 4) { return "****"; } return str.substring(0, 2) + "***" + str.substring(str.length() - 2); });

因为FieldProcessor是函数式接口，所以可以直接用 Lambda 实现。这种方式适合局部定制，不会影响全局默认行为。

6.2 使用 Stream 精简字段收集逻辑

如果你熟悉 Java 8 的 Stream，可以把collect方法中的循环部分改为 Stream 写法，让代码更简洁。下面是一个示意版本：

private List<FieldEntry> collectByStream(Object target) { return Arrays.stream(target.getClass().getDeclaredFields()) .filter(field -> { StyleField styleField = field.getAnnotation(StyleField.class); return styleField == null || !styleField.ignore(); }) .map(field -> { StyleField styleField = field.getAnnotation(StyleField.class); field.setAccessible(true); Object value; try { value = field.get(target); } catch (IllegalAccessException e) { throw new IllegalStateException("读取字段失败: " + field.getName(), e); } if (styleField != null && styleField.mask() != MaskType.NONE && value != null) { value = fieldProcessor.process(value, styleField.mask()); } String name = field.getName(); if (styleField != null && !styleField.alias().isEmpty()) { name = styleField.alias(); } int order = styleField == null ? 0 : styleField.order(); return new FieldEntry(name, value, order); }) .sorted(Comparator.comparingInt(FieldEntry::getOrder)) .collect(Collectors.toList()); }

这种方式更贴近函数式风格，但第一次看代码的人需要适应。如果你更看重可读性，保留原来的 for 循环也没有问题。技术选型没有绝对标准，团队习惯很重要。

6.3 动态代理：对方法返回值统一套用样式

如果项目里到处都是 Service 方法，不可能每个方法都手动调用styler.toText。这时可以结合动态代理做一个薄薄的封装：代理对象调用原方法后，如果返回值是普通 Java 对象，就自动应用 styler。

核心片段如下：

@SuppressWarnings("unchecked") public static <T> T wrap(Class<T> interfaceType, T target, Styler styler) { return (T) Proxy.newProxyInstance( target.getClass().getClassLoader(), new Class<?>[]{interfaceType}, (proxy, method, args) -> { Object result = method.invoke(target, args); if (result != null && isSimpleBean(result.getClass())) { return styler.toText(result); } return result; }); } private static boolean isSimpleBean(Class<?> clazz) { return !clazz.isPrimitive() && !clazz.getName().startsWith("java.") && !clazz.isEnum() && !Iterable.class.isAssignableFrom(clazz); }

动态代理适合用在统一拦截层，但要注意不要对集合、String、基本类型做 styler 转换，否则会把简单类型也格式化掉。这里的isSimpleBean只是一个半成品示例，真正落地时还需要更严谨判断。

7. 常见问题与排查思路

7.1 字段顺序不符合预期

需要特别提醒：反射读取字段的顺序并不等于类中书写的顺序，这是很多新人的认知盲区。所以 styler 必须依赖显式order值排序，不能依赖getDeclaredFields()的返回顺序。

7.2 敏感字段没有脱敏

在设计时，我刻意让null不进入脱敏逻辑，因为 null 本身没有敏感内容，直接输出即可。如果你希望 null 也显示成""，可以在处理器里单独处理。

7.3 私有字段访问异常

在日志量非常大的场景下，建议先判断日志级别，再决定是否调用 styler。否则光生成脱敏字符串就可能造成额外性能开销。

8. 最佳实践与工程建议

8.1 注解语义要清晰，不要堆砌

StyleField注解里已经包含了顺序、别名、脱敏、忽略四种能力，足够覆盖大多数输出场景。但不要在项目里继续堆很多和输出无关的属性，比如权限、国际化、渲染模板等。注解只负责“描述输出规则”，复杂的业务逻辑应该放在独立服务里。

8.2 反射要控制边界

反射虽然方便，但会让代码的静态可读性变差，也会绕过编译期类型检查。在实际项目中建议：

• 把 styler 统一封装成一个组件，不要在业务代码里到处写反射。
• 对高频调用的场景缓存字段元数据，比如用一个Map<Class<?>, List<Field>>。
• 对嵌套对象先做递归深度限制，防止循环引用导致栈溢出。

8.3 日志脱敏是安全底线

日志是排查问题的帮手，但也可能成为敏感信息泄露的入口。使用 styler 输出对象时，password、token、idCard这类字段必须脱敏。不要只在测试环境注意，生产环境要定期扫描日志，查看是否有明文敏感字段。

8.4 为 styler 写充分的单元测试

这类工具类影响范围很大，一旦改错可能影响所有日志输出。建议用 JUnit 写好几个核心场景：

• 字段排序是否正确。
• 每一种脱敏类型是否符合预期。
• 忽略字段是否真的不输出。
• null 值是否正常处理。
• 自定义处理器是否生效。

测试代码是保护重构安全的重要手段。后续升级 JDK 版本、调整反射策略时，跑一遍测试就能快速发现行为变化。

8.5 不要用 styler 代替 DTO 和 VO

虽然 styler 可以按别名输出字段，但它的定位是“展示层工具”，不是完整的 DTO 转换框架。接口对外返回时，如果字段结构复杂、包含嵌套集合，还是应该设计专门的 VO 类。styler 更适合日志、导出、调试等轻量场景。两者可以共存，但职责要分开。

9. 总结与下一步学习方向

本文围绕“布吉岛·鸟鸟岛”项目中的 Java styler，完整介绍了从注解定义、枚举设计、处理器抽象、反射读取、字段排序到脱敏输出的全过程。你不仅可以直接复制代码使用，还能从中理解 Java 注解和反射如何配合，Lambda 和函数式接口怎样提高扩展性，以及LinkedHashMap在保证有序输出时的重要性。

如果你想继续深入，可以从这几个方向入手：第一，阅读一下 Java 的java.lang.reflect包源码，理解Field、Method、Proxy的底层行为；第二，研究 Lombok 的注解处理器实现，了解编译期注解和运行时注解的区别；第三，比较 Jackson 的PropertyNamingStrategy和自定义序列化器，看看成熟框架是如何处理字段命名规则的；第四，尝试给 styler 增加嵌套对象递归输出，让它更适合文档导出场景。

技术工具没有最好的，只有最合适业务的。这套 styler 最大的价值不是代码本身，而是给你提供了一种“用注解描述规则、用反射统一执行”的设计思路。下次遇到类似的重复格式化需求，可以试着先抽象出规则，再考虑具体实现。如果本文对你有帮助，欢迎收藏备用，也欢迎在实际项目中改造出更适合自己团队的版本。