企业官网建设流程全解析

1. 先把“常用工具类”拆清楚

写业务代码久了，你早晚会意识到一个事实：项目里最稳的那部分代码，往往不是某个高难算法，而是公共代码库角落那堆不起眼的StringUtil、DateUtil、FileUtil。这些被统称为“常用工具类”的东西，几乎不承载具体业务语义，却每天要被业务层调用几百次。它们做得好，整个团队写代码都舒服；它们写得乱，新人接手时最先崩溃的就是这个地方。

第 13 讲作为“常用工具类”这个系列的第一篇，我准备把底层的设计逻辑讲透。先别急着写方法，我得先回答三个问题：这些工具类到底在解决什么问题？它们的边界在哪里？为什么同一个功能，有人用第三方的，有人自己封装，还有人两种方式混着来？这三个问题搞明白，后面写代码才有方向。

1.1 它到底属于什么位置

从工程结构看，“常用工具类”位于最底层，是所有业务模块的地基。它不依赖具体的业务对象，也不关心你的订单状态是待支付还是已关闭，它只负责把那些“和业务无关、但又绕不开”的基础操作收拢到一起。

举个最直接的例子：判断一个字符串为空。

你可能会说，这有什么好封装的，直接text == null || text.isEmpty()不就行了？问题是，这种判断在代码里出现 500 次之后，每个人的写法都不一样。有人用""判断，有人用.length() == 0判断，还有人忘了判空直接调trim()，结果就是线上时不时冒出一个 NPE。工具类把这种高频操作收敛成一个方法，顺便规定“空”的边界到底指什么，这就是它存在的核心价值。

所以我习惯把工具类分成三个层级：

• 基础操作类：字符串、集合、日期、文件、正则、加密，这些是纯能力，和业务没有任何关系；
• 场景增强类：比如 Excel 导入导出、HTTP 请求、JSON 序列化，它们封装了某个中间件或框架的通用动作，仍然不算业务专属；
• 业务工具类：针对某个业务域的通用计算，比如“根据订单金额计算优惠分摊”，这种不建议放进公共工具库，因为它会慢慢长成业务逻辑的寄生体。

这个区分特别重要。很多人写工具类写到最后变成一个大杂烩，就是因为他没想清楚第三层和第一层的差别。你一旦把订单相关的规则塞进公共工具类，后面每次改业务都要翻公共库，公共库又会变成“公共垃圾堆”。

1.2 二八法则：哪几类工具最值得投入

按我的经验，一个成熟项目里被调用频率最高的工具类，按热度排大概是这么个顺序：

这个排序不是拍脑袋。你去看一个实际项目的调用统计，字符串和集合这两类基本占据半壁江山。因此这个系列的第一篇，我会把重心放在这两类上，时间与文件单独用实例讲常见的坑，最后再聊封装边界。

2. 字符串工具类：不止是“判空”

很多初学者的字符串工具理解，停留在“防止 NPE”这个层面。但真正写多了就会知道，字符串工具类之所以重要，是因为字符串是所有数据交换的最底层载体。前端传来的参数是字符串，数据库里存的是字符串，日志里打的还是字符串。脏数据、格式不统一、隐藏字符，这些破事几乎全发生在这个环节。

2.1 判空函数怎么设计才不算埋雷

市面上的字符串判空有两个最常用的方法：isEmpty和isBlank。在 Java 里，前者只判断“是不是 null 或长度为 0”，后者还会把纯空格、制表符等不可见字符也算作“空”。

业务开发里，大多数情况下你要判断的是isBlank，不是isEmpty。因为一个用户提交的备注字段大概率是“空格 + 回车”这种组合，如果你只用isEmpty去挡，看起来没空，进库之后全是空白字符。后面做搜索、统计时，这个字段就会变成各种诡异问题的源头。

我自己封装时，会同时提供两个语义明确的方法，而且会在方法注释里写清楚区别：

/** * 判断字符串是否为空（null 或长度为 0） */ public static boolean isEmpty(String text) { return text == null || text.isEmpty(); } /** * 判断字符串是否为空白（null、空串、纯空格、制表符等） */ public static boolean isBlank(String text) { return text == null || text.trim().isEmpty(); }

这里有一个很微妙的设计点：trim()其实只处理首尾小于等于\u0020的空白字符，全角空格不一定被清理掉。如果你面对的是用户输入的中文场景，可能还得考虑用strip()（JDK 11+）或者自己处理全角空格。这就是“看起来简单，但细节全在边缘情况里”的典型例子。

2.2 脱敏、截断与格式转换：工具方法的价值在统一口径

判空只是字符串工具的第一层。真正让工具类发光发热的，是那些“每个业务方都写一遍，但每个地方都写得不一样”的方法。

以手机号脱敏为例。A 团队写的是phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2")，B 团队写的是phone.substring(0, 3) + "****" + phone.substring(7)。两个都能跑，但一个对长度做了正则校验，另一个遇到158这种短号直接崩。把这类逻辑收进工具类，统一用一套正则、一套兜底策略，问题就从“每个调用方自己负责”变成了“工具类只暴露一个maskMobile接口”。

我建议每个字符串工具类至少包含这几类方法：

• 判空与默认值：isBlank、defaultIfBlank；
• 安全转换：字符串转数字时给默认值，避免parseInt直接抛异常；
• 脱敏与掩码：手机号、身份证、邮箱的通用掩码规则；
• 截断与省略：超长文本加省略号，同时避免截断时出现半个字符；
• 命名风格互转：驼峰转下划线、下划线转驼峰，字段映射时特别有用；
• 占位符拼装：用{}做占位，替代容易出错的字符串拼接。

这里我最想强调“安全转换”。很多线上事故不是复杂的并发问题，而是接口传了个"abc"给你，你用Integer.parseInt一把梭，结果就是 500 错误。工具类里做一个toInt(String text, int defaultValue)，把异常吞掉并返回兜底值，这种“防御式”写法在接口对接场景里能省非常多事。

代码示例可以长这样：

public static int toInt(String text, int defaultValue) { if (isBlank(text)) { return defaultValue; } try { return Integer.parseInt(text.trim()); } catch (NumberFormatException e) { return defaultValue; } }

注意，这里的“兜底”不是让你掩盖异常。对于关键参数，你完全可以在调用方继续做严格校验；工具类只是把“最常用的默认分支”提出来，避免每个调用点都贴一段 try-catch。

3. 集合工具类：从遍历到分组的写法演进

如果说字符串工具类是“防脏数据”，那集合工具类就是“防低效代码”。Java 8 之后 Stream 让集合操作变得很优雅，但 Stream 不是万能的，而且用得不对反而比传统 for 循环更容易踩坑。

3.1 判空与安全遍历

集合判空也是一个经典话题。很多人写代码时喜欢这样：

if (list != null && list.size() > 0) { // do something }

这句没问题，但不够统一。如果项目里有 100 处这种判断，你很难保证每一处都记得先判 null。工具类可以提供一个更清晰的入口：

public static boolean isEmpty(Collection<?> collection) { return collection == null || collection.isEmpty(); }

有了这个之后，调用方就变成了：

if (!CollectionUtils.isEmpty(userList)) { // do something }

代码写起来简洁，而且语义更接近人的阅读习惯。同样的思路还可以用在 Map 上。特别注意一点：判断空之前，先想想这个集合允许不允许为 null。如果某个方法内部绝不会返回 null，那你就没必要在外面套一层判空，多此一举还会让代码更乱。

我在实际项目里发现一个很有意思的规律：新手喜欢到处判空，因为怕 NPE；老手喜欢在源头就消灭 null，能返回空集合就返回空集合。工具类存在的意义不是让你继续容忍 null，而是在你无法改变老代码的情况下，给一个安全兜底。

3.2 列表转 Map：一个隐藏的坑

集合工具里最高频、也最容易写错的操作，我觉得是“List 转 Map”。用 Stream 的Collectors.toMap一行代码确实很爽，但它有两个隐藏的行为：

• 如果列表里有重复 key，默认会抛IllegalStateException；
• 如果 value 是 null，部分 JDK 版本下会抛NullPointerException。

这两个异常都是运行时异常，测试环境数据量小不一定触发，一上生产就原形毕露。所以我会在工具类里封装一个“转 Map 并保留重复项”的方法，而不是让每个调用方都去处理那套烦人的 merge 逻辑：

public static <K, V> Map<K, V> toMap(List<V> list, Function<? super V, ? extends K> keyExtractor) { if (list == null || list.isEmpty()) { return new HashMap<>(); } Map<K, V> map = new HashMap<>(); for (V item : list) { K key = keyExtractor.apply(item); // 重复 key 时保留最后一条，或者按业务覆盖 map.put(key, item); } return map; }

这种封装的核心思路叫“窄化接口”。我把Collectors.toMap暴露给业务方之前，先在工具层把异常策略定死。要么报错，要么覆盖，要么保留最早的，业务侧不用各写一套，后续排查问题也简单。

3.3 分组、去重、映射：工具方法的组合拳

再往下说，集合操作里还有三个高频场景：按字段分组、按字段去重、提取某个属性列表。

按字段分组用Collectors.groupingBy就行，但注意分组结果默认是HashMap，如果你需要有序分组，要传LinkedHashMap：

Map<Integer, List<User>> group = list.stream() .collect(Collectors.groupingBy(User::getAge, LinkedHashMap::new, Collectors.toList()));

提取属性列表，也就是把一个List<User>变成List<String>，同理。

去重这个点最容易被人忽略。很多人一听到去重就想到distinct()，但distinct()是按整个对象去重，不是按某个字段去重。如果你想按“用户 ID”去重，得用TreeSet或者自定义过滤器。工具类里做一个“按字段去重”的方法，能避免业务方到处写匿名内部类。

我踩过一次印象很深的坑：当时导出名单，要求按手机号去重，我用distinct()一顿操作，测试数据没问题，上线之后才发现同一批数据里有两个人手机号相同但姓名不同，distinct()根本没拦下来。从那以后我就把这类“按 key 去重”的逻辑固定进工具库，不允许业务方自己造轮子。

4. 时间与文件：最易踩坑的两类工具

字符串和集合用多了，顶多是性能问题；但时间日期和文件 IO 这两类工具用错了，往往直接就是可见的事故。而且它们还有一个共同点：单测很难覆盖所有边界场景，所以更依赖工具类提前把规则固化。

4.1 时间格式化：别在并发环境里用 SimpleDateFormat

SimpleDateFormat是一个被讲烂了的问题，但我每次代码审查还是能看到有人在业务里新建一个静态实例来用：

private static final SimpleDateFormat SDF = new SimpleDateFormat("yyyy-MM-dd");

这里有个背景知识：SimpleDateFormat不是线程安全的，它的内部用了一个Calendar的共享实例。多线程并发调用format或parse时，可能出现错乱，表现为日期格式化结果偶尔差几个月，甚至直接抛NumberFormatException。

解决方案并不复杂——优先用DateTimeFormatter，它是线程安全的：

private static final DateTimeFormatter FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); public static String format(LocalDateTime time) { return FMT.format(time); }

如果你还在维护老系统，必须用SimpleDateFormat，那至少每次调用都 new 一个实例，或者用ThreadLocal包一层。工具类里我强烈建议直接切到DateTimeFormatter，早切早省心。

另外，时间工具类里还有一个经常被忽略的点：区间计算。比如“计算两个日期相差几天”，如果直接用毫秒数除以一天的毫秒数，会因为夏令时、闰秒等问题出现偏差。更稳妥的做法是使用java.time.temporal.ChronoUnit或者Period。

4.2 文件读取：路径、编码、关闭流一个都不能少

文件类工具的重点不在“读得有多快”，而在“读完之后资源有没有关”。早期 JDK 7 以前，写文件流需要手动在 finally 里关闭；现在有了 try-with-resources，代码可以清爽很多：

public static List<String> readLines(String path) throws IOException { try (BufferedReader reader = new BufferedReader( new InputStreamReader(new FileInputStream(path), StandardCharsets.UTF_8))) { return reader.lines().collect(Collectors.toList()); } }

注意我这里显式指定了 UTF-8。很多人不指定编码，依赖系统默认编码，项目换一台服务器，中文文件全变乱码。这个坑我已经见过不止一次，而且每次都是上线后才被运营发现。文件 IO 相关的方法，编码必须写死，不允许用平台默认值。

大文件的读取又是一个场景。如果你是拿着一份 2GB 的日志去做逐行处理，千万别一次性readAllLines，内存直接被打爆。正确姿势是用流式读取，边读边处理：

try (Stream<String> lines = Files.lines(Paths.get(path), StandardCharsets.UTF_8)) { lines.filter(line -> line.contains("ERROR")) .limit(1000) .forEach(System.out::println); }

工具类的作用在这里就体现得很明显：统一编码、统一关闭流、统一异常策略。业务方只需要关心“我要读哪个文件、怎么处理每一行”。

4.3 文件路径拼接：别用字符串“+”

文件工具类里还有一个很不起眼但很致命的问题：路径拼接。很多人图省事直接String path = basePath + "/" + fileName，遇到 Windows 环境就变成D:\data\user.csv，结果 basePath 结尾带不带斜杠、文件名里有没有特殊字符，全都要靠调用方自觉。

正确的做法是使用Paths.get(basePath, fileName)，它会根据运行平台自动补齐分隔符：

Path filePath = Paths.get(basePath, fileName);

这个细节我一般不会在代码注释里写，但会在工具类封装时尽量“顺手做掉”，让调用方少一个可犯错的机会。

5. 自己封装还是引三方：边界到底在哪

到这里，你应该已经发现，市面上已经有成熟的三方工具包在做这些事，最常见的就是 Apache Commons Lang、Google Guava、Hutool。于是很多人会问：既然别人已经写好了，我为什么还要自己封装？

我的回答是：你可以站在巨人的肩膀上，但不能把巨人的全部家当都搬到业务代码里。工具类的选型，本质上是一种工程权衡。

5.1 三方工具库的优点与代价

先说优点。Apache Commons 和 Guava 经过多年大规模生产环境验证，边缘情况处理得比绝大多数团队自己写的要好。比如说判空，Guava 的Strings.isNullOrEmpty、Apache 的StringUtils.isBlank，都是经过大量用户踩坑后沉淀出的实践。直接用它们，你至少不用重新发明轮子。

再看代价。引入一个工具库，意味着它的所有 API 都会暴露在你的代码库里。团队里如果没人熟悉 Guava 的ImmutableList语义，有人写了个ImmutableList.of，结果被另一个人add的时候报UnsupportedOperationException，这个排查成本比省下的那几行代码高得多。

另一个代价是版本冲突。多个模块引了不同版本的 Commons Lang，可能出现NoSuchMethodError，这是 JVM 生态里非常恶心的一个问题。工具库虽然是好东西，但如果只是用其中两三个方法，完全可以用一种更轻量的方式收口。

5.2 我的封装策略：薄封装 + 固定语义

我自己更偏向一种“薄封装”的做法：核心实现可以委托给成熟的三方库，但暴露给业务方的入口是团队自定义的工具类，在里面固定一套语义。

举个实际例子：

public final class TextUtil { public static boolean isBlank(String text) { return text == null || text.trim().isEmpty(); } public static String maskMobile(String mobile) { if (isBlank(mobile) || mobile.length() < 7) { return mobile; } return mobile.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2"); } }

这个TextUtil不依赖任何三方包，方法数量也不多，但每个团队看到这个名字，都知道去哪找“判空”和“脱敏”。它不像直接调StringUtils那样散乱，也不像那种 2000 行的CommonUtil那样失控。

薄封装的核心原则有三条：

• 方法语义由团队定义：外层展示的是团队统一的规范，底层可以是原生 JDK，也可以是三方库；
• 方法数量克制：只封装被重复调用超过 3 次的操作，不要预设一堆“将来可能用得上”的方法；
• 不允许随意扩展业务逻辑：公共工具类只放基础能力，业务规则必须下沉到业务模块。

这个原则特别重要。你可以把这个公共工具类看成一个“接口面”，它挡住背后第三方库的变化，同时控制团队的使用习惯。

5.3 什么时候必须引三方

薄封装不代表“禁止引三方”。有些领域，自己写的成本远高于引入成熟库的成本，我帮你把这些场景列出来：

这里想特别说一句：如果你只是需要一个“CollectionUtils.isEmpty”，真没必要为了这个引入 Guava。你可以用 JDK 原生实现，也可以引入，但要在团队规范里说清楚，避免每个人都引一个不同库。

我见过最夸张的场景：一个项目里同时引了 Guava、Hutool、Apache Commons Lang，以及三个 JSON 库。功能确实都能用，但维护的人每次都要思考“这个项目里StringUtils到底指的是哪个”，这种隐性成本比任何工具方法都贵。

6. 实战排雷笔记：那些别人文档里不会写的细节

工具类看着简单，实际落地时总能碰到几个“看起来不应该出错但就是出错了”的场景。我把这些年积累的几个典型问题整理成一张表，并重点展开其中两个。

6.1 一个由全角空格引发的线上问题

有次做搜索功能，用户在前端输入了一个全角空格，提交到后端，我们用isEmpty判断没拦截下来，结果这个“看起来是空”的字符串进入查询条件，导致搜索结果一直是空列表。排查了很久，才发现问题根本不在搜索逻辑，而在“空字符串的判定口径”。

从那以后，我对于所有“用户输入型字段”的统一校验，一律用isBlank，并且在全角空格的处理上做了额外兼容。这个细节，普通教科书上不会写，但它就是真实业务里最容易炸的点。

6.2 大数据量导出：工具方法也要考虑分批

还有一个印象很深的案例。当时一个导出功能，收集了几十万条数据后统一写入 Excel。第一版代码很直观：先查全量，再循环 set 单元格，最后一次性写文件。测试的时候数据量小没发现问题，上线后运营一点导出，应用直接 OOM。

后来我把文件写入改成流式，并且分批从数据库查询，每 5000 条写一个批次，内存占用一下子降下来了。这个教训让我明白：工具类不是只封装“基础操作”，还要在接口设计时就考虑到数据量。比如文件导出这种场景，方法签名要支持“传入一个分页查询函数”，而不是“传入一个全量 List”。

7. 我的个人使用习惯：让工具类保持“瘦”

聊到最后，我再说一个我在实际项目里坚持的习惯：给工具类做“瘦身体检”。

每个季度，我会把公共工具类的方法列一遍，统计调用次数。如果一个方法已经被半年都没人调用，我就会强烈提议把它删掉。因为无人调用的工具方法，大概率是一种“面向未来编程”，而面向未来编程的常态是：未来没来，代码变垃圾。工具类真正需要的是“被高频使用的方法，以统一的方式稳定输出”，而不是“把所有可能用到的场景堆在一处”。

如果你刚开始整理自己项目的工具类，我的建议非常简单：从字符串和集合各挑 5 个最常用的方法，以薄封装的方式固化下来，其他一律先不碰。之后每遇到一次“同样的代码写了第三遍”，再考虑要不要把它提炼进工具类。用这种节奏维护出来的工具库，不会大而全，但一定小而精，而且团队里每个人都知道该去哪里找什么。