Java实战：从零构建名片管理系统，详解集合、锁与缓存架构

你有没有算过，一年下来自己手里会积攒多少张名片？我去年认真统计过一次——线下会议收了两百多张纸质名片，行业交流群里互加的微信好友三百多个，还有一些扫过就忘的电子名片。真正让我崩溃的是，某次想找一个三年前合作过的供应商负责人，翻了整整两天的抽屉、相册和聊天记录，最后还是没找到。那之后我就萌生了一个念头：能不能用我最熟悉的Java，自己动手做一套名片管理系统？

说做就做，我把这个项目命名为“易卡随行”。花了一个多月时间，从设计数据库到写核心代码，再到处理各种性能和数据一致性问题，整个过程踩了不少坑，也把很多平时只在面试题里见到的知识点真正用到了项目里。这篇文章不是贴一堆教学代码就完事，而是把我做这个项目时的技术选型思路、核心功能实现、遇到的问题和解决方案，完整记录下来。如果你是Java开发者，或者想用Java做一个完整项目的初学者，这篇内容应该能给你不少参考。

1. 从纸质名片到“易卡随行”：项目背景与Java技术选型

1.1 传统名片管理到底痛在哪里

名片的痛点主要集中在三个层面。第一个层面是物理层面的散落：纸质名片散落在各种钱包、抽屉、名片夹里，电子名片散落在微信聊天记录、邮件签名、手机通讯录里，信息源太多，等于没有统一的信息源。第二个层面是检索层面的困难：真正要找一个联系人的时候，你很难通过一个统一的搜索入口把信息捞出来，只能靠记忆去猜哪个地方能找到。第三个层面是关系维护层面的缺失：名片收进来了，可是这个人多久没联系了、在哪个场合认识的、有什么共同合作记录，这些关系数据完全没有沉淀。

我做“易卡随行”的目标很明确，不是简单地做一个电子通讯录，而是把名片的录入、归档、检索、交换、关系维护全部串联起来。相当于给每一张名片都建立了完整的生命周期档案，这也是我把项目副标题定为“重构名片管理新生态”的原因——不只解决“把名片存起来”的问题，而是解决“名片背后的人脉怎么维护”的问题。

1.2 为什么技术栈选了Java

其实做名片管理系统的方案很多，可以用纯前端加本地存储，可以用Python写个小脚本，也可以用Node.js做一个轻服务。我之所以选择Java，有几个比较实际的考虑。

第一个是生态成熟度。名片系统虽然业务不复杂，但一旦要做OCR识别名片、做全文搜索、做数据统计报表，Java生态里对应的库和中间件非常丰富，而且资料多、踩坑案例多，遇到问题搜一搜基本都能找到解决方案。

第二个是跨平台部署能力。我自己的电脑是Windows，服务器是Linux，Java的“一次编写，到处运行”在这种环境切换下非常省心。而且如果后续要把这套系统推广到公司内部使用，目标机器上的JDK是现成的，几乎不用额外做兼容适配。

第三个是学习杠杆。说实话我自己也在准备面试，Java相关的基础、集合、并发、JVM这些知识点，做项目之前很多都停留在面试题层面，做一遍真实项目之后，对很多概念的理解会深入很多。比如面试八股文里常问的HashMap原理、Lock和synchronized区别、反射机制，如果只是在题目里见到，背完就忘，但在项目里真正用过一次，印象会特别深刻。

最终确定的技术栈是这样的：

这里多说一句，很多人问为什么不用MyBatis而用JPA。名片系统的表结构相对简单，实体关系也不复杂，用JPA可以让我把精力放在业务逻辑上，实体类写好之后CRUD几乎不用写SQL。如果你习惯MyBatis也没问题，不影响整体架构，关键是把分层和边界理清楚。

1.3 系统功能全貌

“易卡随行”第一版规划的功能有六个模块：名片录入、分组管理、标签体系、全文检索、名片交换、数据统计。名片录入支持手填和批量导入Excel；分组管理解决的是“把名片按客户、供应商、同事、朋友等维度归档”的问题；标签体系比分组更灵活，一张名片可以打多个标签，比如“高潜力客户”“游戏行业”“在深圳”；全文检索支持按姓名、公司、职位、手机号模糊搜索；名片交换解决的是“两个人面对面互加名片后，如何防止重复数据”的问题；数据统计则是按来源、行业、时间维度统计名片的增长情况。

2. 工程落地第一步：环境配置与整体架构搭建

2.1 Java安装与环境变量配置

这一步看着简单，但很多人（包括以前的我）都在这上面翻过车。我先说结论：Java环境变量配置的核心是三个变量——JAVA_HOME、PATH、CLASS_PATH。

具体步骤是这样的：

1. 去Oracle官网下载JDK 17的安装包，注意选择对应操作系统的版本，Windows选择.exe安装包即可。
2. 安装时记住安装路径，比如 D:\Java\jdk-17。
3. 打开系统环境变量设置，新建 JAVA_HOME，变量值填 D:\Java\jdk-17。
4. 编辑 PATH，新增一条 %JAVA_HOME%\bin。
5. CLASS_PATH 建议配为 .;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar，配置在用户变量里防止影响整个系统。

配置完打开CMD，输入 java -version 和 javac -version，如果两个命令都能正确输出版本号，说明环境就OK了。

我当时踩的坑是：安装完JDK之后直接把JDK安装目录下的bin路径写死到了PATH，结果卸载重装JDK之后，java -version始终显示旧版本。后来发现是PATH里残留了旧版本的bin路径，而且顺序还在新版本之前。Windows的PATH是从前往后找的，找到第一个java.exe就直接运行了。这也是为什么强烈建议用JAVA_HOME做一层中转，以后换版本只需要改JAVA_HOME的值。

2.2 Maven与项目骨架

依赖管理方面，我用Maven而不是手动拉jar包。核心原因是Maven能够解决依赖传递和版本冲突。名片系统会用到Spring Boot、MySQL驱动、Redis客户端、POI（Excel导入）、Zxing（二维码生成）这些依赖，如果用传统方式把jar包拷到lib目录，版本冲突会让人崩溃。比如Spring Boot 3.x要求必须使用Java 17，如果某个间接依赖被错误解析成旧版本，运行时会出现各种NoClassDefFoundError。

在pom.xml中，我引入Spring Boot的parent（这里展示关键片段）：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.0</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.33</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>

2.3 分层架构

“易卡随行”采用经典的分层架构，我分了四层：

• controller层：只负责接收HTTP请求、参数校验、返回结果。
• service层：承载业务逻辑，比如名片去重、交换流程、统计计算。
• repository层：继承JpaRepository，完成数据访问。
• dto/vo层：负责接口入参出参定义，避免实体直接暴露给前端。

分层的好处是职责单一。比如后来我在做名片交换的并发控制时，只需要改动service层，controller和repository完全不用动，几个核心类测试通过，其他模块基本不受影响。这个收益在刚起步时看不出来，等模块越来越多、改动越来越频繁时，分层的价值会非常明显。

3. 名片核心模型设计：面向对象思想与Java集合实战

3.1 名片实体类：封装、继承与多态

名片的核心实体是Card。在设计这个类的时候，我特别注意了几个Java基础但很重要的点。

第一个是封装。所有字段都是private，对外通过getter/setter访问。我用了Lombok的@Data注解减少样板代码，但如果你还在学习阶段，我建议手写一遍getter/setter，把封装的概念吃透再用Lombok。这个过程的差别就像先学会手动挡再开自动挡，虽然自动挡更方便，但手动挡能让你真正理解引擎运转的原理。

第二个是继承和接口。不同类型的名片行为不同，比如个人名片有职位层级的概念，企业名片有部门规模的概念，但它们又都有被扫描、被检索的共性。我定义了一个CardEntity基类，再让PersonalCardEntity和CompanyCardEntity继承它。这个继承结构让代码复用了大量公共字段，同时给未来的扩展留了空间。

第三个是Java标识符命名规则。这里包含两个层面：一是Java语法层面的要求，比如字段名不能以数字开头、不能用关键字；二是JavaBeans规范层面的约定，比如属性名应该以小写字母开头。语法层面的错误编译器会直接报错，最容易出问题的是后者——我之前定义了一个叫URL的字段，结果在JSON序列化时变成了“url”，和联调方对不上，后面我会在踩坑部分详细展开。

下面是我简化后的实体类：

@Data @Entity @Inheritance(strategy = InheritanceType.JOINED) public class CardEntity { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String name; private String company; private String title; private String mobile; @Column(length = 500) private String remark; @Enumerated(EnumType.STRING) private CardSource source; private LocalDateTime createdAt; private LocalDateTime updatedAt; }

3.2 集合框架：从ArrayList到HashMap

名片系统里集合用得非常多。比如从Excel导入名片时，先用ArrayList暂存所有解析出来的记录，然后通过Set做去重。名片分组时，用Map<Long, List >来维护“分组ID到名片列表”的映射关系。打标签时，用Set 保证同一张名片不会重复添加同一个标签。

其中有一个使用细节值得说一下。Excel导入的时候，如果数据量达到几千条，直接用ArrayList逐条调用save()方法插入数据库，性能会非常差，因为每条记录都会触发一次SQL。我当时改成用Set去重后，再通过saveAll批量插入，耗时从原来的几十秒降到几秒。

Set<String> seen = new HashSet<>(); List<CardEntity> toSave = new ArrayList<>(); for (CardRow row : rows) { String key = row.getName() + "|" + row.getMobile(); if (seen.add(key)) { toSave.add(buildCard(row)); } } cardRepository.saveAll(toSave);

这里用了哈希集合的一个特性：add方法返回boolean值，如果元素已经存在，返回false且不会重复加入。用这个特性做去重，比先contains再add高效得多，时间复杂度从O(n)降到O(1)。类似的想法，在Java面试里经常会被问到HashSet去重和HashMap的原理，做过这个场景之后再理解底层哈希桶、hash计算等概念，会觉得顺畅很多。

3.3 枚举、泛型与字符串新特性

名片来源我定义成了枚举CardSource，包含MEETING、ONLINE、EXCEL、QR_CODE等值。为什么用枚举而不是直接存字符串？因为枚举能约束取值范围，而且在业务逻辑里可以加具体行为。比如每个来源在统计时都有一个显示名称和图标类名，我把这些字段直接挂在枚举上，用起来非常方便。

泛型我用在统一返回结果上。定义了一个Result 类，成功返回Result.success(data)，失败返回Result.fail(code, msg)，前端拿到后根据code判断业务逻辑。这个包装类在REST接口设计里几乎是标配，也是泛型最典型的应用场景之一。

字符串方面，Java 15之后支持Text Block，我在拼接名片的长描述文本时用得非常爽。比如生成名片二维码的内容时，需要把一个多行JSON字符串拼进去，以前要写一堆\n和引号转义，现在直接写三引号块：

String qrContent = """ { "id": "%d", "name": "%s", "company": "%s", "mobile": "%s" } """.formatted(card.getId(), card.getName(), card.getCompany(), card.getMobile());

这段代码的可读性比老式的字符串拼接好了太多，日常开发里遇到多行模板字符串时，Text Block几乎成了我的首选。

4. 批量处理与查询提速：Lambda、Stream与函数式编程

4.1 为什么项目里要大量用Lambda

很多人觉得Lambda只是语法糖，少写几个字母而已。但在我做名片系统的过程中，Lambda和Stream真正的价值不是少写代码，而是改变了思考方式。

举个例子，我需要筛选出所有深圳地区的客户名片，并且按最近更新时间排序，然后只取前50个做运营回访名单。用传统for循环写需要四五行的循环加判断加列表拼接，用Stream只需要一行链式调用：

List<CardEntity> candidates = cardList.stream() .filter(c -> "深圳".equals(c.getRegion())) .filter(c -> c.getCustomerTag()) .sorted(Comparator.comparing(CardEntity::getUpdatedAt).reversed()) .limit(50) .collect(Collectors.toList());

这段代码可读性非常高，从语义上就能看明白筛选链路。而且Comparator.comparing配合方法引用CardEntity::getUpdatedAt，避免了手写匿名Comparator类的冗长代码。如果你在面试八股文里准备过Comparator和Lambda，这就是最好的结合案例。

4.2 函数式接口的实战场景

Java内置的函数式接口在项目里用得最多的是Consumer、Function和Predicate。

Predicate的典型场景是动态拼接筛选条件。名片列表页需要支持按姓名、公司、职位、标签、地区等多个条件组合筛选，如果条件非常多，用if判断拼接SQL很痛苦。我改用Predicate组合的方式：

Predicate<CardEntity> condition = c -> true; if (StringUtils.hasText(keyword)) { condition = condition.and(c -> c.getName().contains(keyword) || c.getCompany().contains(keyword) || c.getTitle().contains(keyword)); } if (StringUtils.hasText(region)) { condition = condition.and(c -> region.equals(c.getRegion())); } List<CardEntity> result = cardList.stream().filter(condition).toList();

这种方式在数据量不大（比如几千张名片）的情况下完全够用，而且避免了拼接SQL可能导致的注入风险。等数据量真正大到需要走数据库索引的时候，再切换成QueryDSL或者JPA Specification也不迟。

Function接口则用在了DTO转换上。Entity要转成VO时，我定义了一个转换器函数：

Function<CardEntity, CardVO> converter = entity -> { CardVO vo = new CardVO(); BeanUtils.copyProperties(entity, vo); vo.setSourceDesc(entity.getSource().getDisplayName()); return vo; }; List<CardVO> voList = cardList.stream().map(converter).toList();

4.3 Stream的并行流与性能边界

当名片数据量达到几万条时，单线程的流处理开始变慢。我尝试过用parallelStream()做并行处理。这里要特别提醒：并行流不是免费的午餐，它在底层使用的是ForkJoinPool公共线程池，如果不分青红皂白地对所有流操作都使用并行，反而会因为线程切换开销导致性能下降。

我的实测结论是：在名片去重、批量转DTO这种CPU密集型且无共享可变状态的场景下，并行流能提升大概30%到50%的性能。但一旦涉及带状态的累加操作，比如计算每个分组下的名片数，并行流就会出现线程安全问题，这时候还是老老实实用Collectors.groupingBy更稳妥。

Map<String, Long> countByCompany = cardList.stream() .collect(Collectors.groupingBy(CardEntity::getCompany, Collectors.counting()));

这个案例也说明了一个原则：Stream操作虽然优雅，但必须清楚它的执行模型和副作用约束。在并行流里操作共享的ArrayList或者HashMap，很容易出现数据错乱，排查起来还特别困难。

5. 缓存与持久化：Redis、MySQL在名片系统中的配合使用

5.1 数据库设计与JPA使用

名片系统的数据库表设计遵循了常规的范式化思路。核心表是card表，存储名片基本信息；group表存储分组；card_tag表存储标签；card_group_relation表存储名片和分组的关联关系。因为用了JPA的@ManyToMany和@OneToMany映射，这些关联关系在Java侧处理起来比较方便。

但这里我要说一个真实的教训：JPA的一对多关联如果处理不当，会产生N+1查询问题。比如我要展示一组名片列表，每张名片下面要带上它所属的标签列表，如果直接遍历每张名片去查标签，就会产生“1（列表查询）+ N（标签查询）”条SQL。当名片数量达到几百张时，接口响应时间立刻感知得到。

解决办法可以是使用@EntityGraph显式指定关联字段的抓取策略，也可以在查询时使用JOIN FETCH。我最终采用的方式是，在Repository里定义带@EntityGraph的查询方法：

public interface CardRepository extends JpaRepository<CardEntity, Long> { @EntityGraph(attributePaths = {"tags"}) @Query("select c from CardEntity c where c.deleted = false") List<CardEntity> findAllWithTags(); }

这样查询名片列表时，会一次性把tags关联出来，SQL从“1+N”变成“1+1”，性能提升非常明显。这个问题在面试中常被问到，但如果你没有在实际项目里遇到过，很难理解为什么JPA会产生N+1查询。

5.2 Redis的缓存场景：热点名片与名片浏览计数

Redis在这个项目里承担了三类任务：热点名片缓存、名片浏览量计数器、分布式锁。

热点名片缓存很好理解，一些大V的名片会被频繁访问，如果每次都去MySQL查，数据库压力比较大。我把这类名片的数据在Redis里存了一份，key用的是card:detail:{id}，过期时间设置30分钟，配合逻辑过期策略做缓存重建。

名片浏览量计数器用的是Redis的INCR命令。每被访问一次，就执行一次increment操作，每隔一段时间把计数批量同步到MySQL。

这里就涉及到一个非常经典的坑：RedisTemplate的increment报错“not an integer or out of range”。我当时已经能正常用StringRedisTemplate操作了，但换到RedisTemplate后就报这个错。排查了半天发现原因有两个。

第一个原因是value的序列化器不对。如果使用RedisTemplate且没有指定value序列化器，默认用的是JDK序列化，这时先把一个字符串值存了进去，然后又对它执行increment，Redis一检查发现value不是整数，就报了“not an integer or out of range”。

解决办法是给RedisTemplate配置专门的String序列化器：

@Bean public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); StringRedisSerializer stringRedisSerializer = new StringRedisSerializer(); template.setKeySerializer(stringRedisSerializer); template.setValueSerializer(new GenericJackson2JsonRedisSerializer()); template.setHashKeySerializer(stringRedisSerializer); template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer()); template.afterPropertiesSet(); return template; }

第二个原因是value本身不是整数。有一次在测试环境手动在Redis里设置了card:views:123的值为“abc”，再跑increment时同样报错。这属于脏数据问题，清理掉就好。这两类原因在排查时一定要分开看，先确认key存储的实际value是什么、再确认序列化器是否兼容。

5.3 缓存一致性：延迟双删模式的实践

名片信息更新时，需要同步更新Redis缓存。最粗暴的方案是更新数据库后直接删缓存，但高并发下容易出现缓存和数据库不一致的问题。我采用的是延迟双删模式：

1. 先删除缓存
2. 更新MySQL数据库
3. 休眠几百毫秒
4. 再次删除缓存

为什么要延迟再删一次？因为某个线程在第一步删缓存之前如果已经读到了旧数据，它可能在更新期间把旧数据写回缓存。延迟删除能把这种“残留旧数据”再清一次。这个方案不完美，但在名片系统这种业务场景下已经足够可靠，而且实现成本低。

比起那些复杂的缓存一致性协议，延迟双删在中小型项目里是性价比比较高的选择。前提是接受短暂的不一致窗口，这个窗口大概是几百毫秒，对名片这种对实时性要求不高的业务来说，完全没问题。

6. 抢名片与并发交换：锁机制和高并发处理实战

6.1 业务场景：限量名片码的分配

名片系统里有一个功能是“限量名片码”，名片主人可以设置一个总码数，比如500个，别人扫他的名片码时，如果还有剩余额度就能成功加名片，超过500就无法添加。这本质上就是分布式场景下的资源扣减问题。

最开始我直接用MySQL的UPDATE语句扣减：

UPDATE card SET remaining_count = remaining_count - 1 WHERE id = ? AND remaining_count > 0

这是乐观锁思路，依靠数据库的行锁来保证更新原子性，在单应用实例下完全没有问题。剩余几个名额就只会成功扣几次。

后来业务要求统计每个名片码在每天各时段的被扫次数，同时在多个应用实例部署时也不能超发。这时我开始研究Redis分布式锁。我用的是RedisTemplate + SetNX命令实现的简易分布式锁。

6.2 synchronized与ReentrantLock的局限

先说单实例的情况。如果应用只部署一个实例，直接在方法上加synchronized就能保证同一时刻只有一个线程执行扣减逻辑。但synchronized有两个问题：一是它只对单个JVM内的线程有效，多实例部署时就失效了；二是使用不当会导致锁的粒度过大，把整个交换流程都锁住，性能很差。

ReentrantLock比synchronized灵活的地方在于支持超时获取锁、支持公平锁/非公平锁选择。我早期用ReentrantLock写过一个版本，用tryLock加超时时间来控制等待时间：

private final ReentrantLock lock = new ReentrantLock(true); public boolean exchangeCard(Long cardId) { if (lock.tryLock(3, TimeUnit.SECONDS)) { try { // 扣减名额、生成交换记录 } finally { lock.unlock(); } } return false; }

这里特别说一下公平锁参数true的作用。在高并发场景下，如果大量线程同时请求同一张名片的码，非公平锁可能导致某些线程一直抢不到锁，也就是线程饥饿。公平锁会按照请求顺序排列，虽然吞吐量会略低，但稳定性更好。名片交换这种业务对公平性有一定要求，我先用的是公平锁。

6.3 分布式锁与常见陷阱

当我把应用部署到两个实例时，本地锁就失效了。这时候需要把锁放到所有实例都能访问到的地方，也就是Redis。

我用Redis实现分布式锁的核心代码是：

String lockKey = "lock:card:" + cardId; String requestId = UUID.randomUUID().toString(); Boolean locked = redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, 10, TimeUnit.SECONDS); if (Boolean.TRUE.equals(locked)) { try { // 扣减名额、生成交换记录 } finally { String script = """ if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end """; redisTemplate.execute(new DefaultRedisScript<>(script, Long.class), List.of(lockKey), requestId); } }

这里有两个非常关键的细节。第一，setIfAbsent必须指定过期时间，否则如果获取锁后应用宕机，锁永远不会释放，其他线程全部阻塞等待直到超时。第二，释放锁时必须用Lua脚本判断持有者身份，只删除自己加的锁。如果不判断直接删除，可能出现这种情况：线程A拿到锁后执行时间较长，锁自动过期了，线程B拿到锁，此时A执行完释放锁，直接把B的锁给删了，这样就乱套了。

这两个问题在面试题里经常以“怎么实现一个靠谱的分布式锁”出现，但只有真正在并发场景下踩过坑，才能理解为什么Redis官方推荐的Redisson里要内置看门狗机制来延长锁的过期时间。名片交换场景的锁持有时长非常短，所以简单的SetNX方案就够用了，但如果锁内要做远程调用、耗时操作，就需要考虑更健壮的实现。

7. 可扩展架构：反射、动态代理与设计模式的应用

7.1 反射：动态处理不同类型的名片导入策略

“易卡随行”支持多种导入方式，包括Excel导入、二维码扫码导入、OCR图片识别导入。每种导入工具类不同、解析逻辑不同，为了让新增导入方式不需要改动核心service代码，我用工厂模式加反射做了一个导入器注册中心。

具体做法是：定义CardImporter接口，所有导入器实现这个接口。在导入器类上加上自定义注解@ImporterType("excel")，系统启动时通过反射扫描到所有带该注解的类，注册到Map中：

@Component public class ImporterRegistry implements ApplicationRunner { private final Map<String, CardImporter> registry = new HashMap<>(); @Override public void run(ApplicationArguments args) { Reflections reflections = new Reflections("com.yika.card.importer"); Set<Class<?>> classes = reflections.getTypesAnnotatedWith(ImporterType.class); for (Class<?> clazz : classes) { ImporterType annotation = clazz.getAnnotation(ImporterType.class); try { CardImporter importer = (CardImporter) clazz.getDeclaredConstructor().newInstance(); registry.put(annotation.value(), importer); } catch (Exception e) { log.error("注册导入器失败: {}", clazz.getName(), e); } } } public CardImporter getImporter(String type) { return registry.get(type); } }

这其实是工厂模式加反射的组合应用。以后如果新增一个名片导入方式（比如从CSV导入、从钉钉通讯录导入），只需要新增一个类加一个注解，不用修改任何核心逻辑。反射是Java面试里非常高频的知识点，这里用到的getDeclaredConstructor().newInstance()就是反射创建对象的经典方式。

7.2 动态代理：给名片交换加权限校验

动态代理在这个项目里用在了接口调用权限控制上。有些操作需要登录用户才能执行，比如修改名片、删除名片、发起交换。如果每个Controller方法都手动写一遍权限判断，代码会非常冗余。我用JDK动态代理做了一个权限拦截器。

核心思路是：定义带有@RequireLogin注解的Service接口，然后通过Proxy.newProxyInstance生成代理对象，在代理逻辑里先校验登录态，再调用真实方法。

public class PermissionProxy implements InvocationHandler { private final Object target; private final UserContext userContext; public PermissionProxy(Object target, UserContext userContext) { this.target = target; this.userContext = userContext; } @Override public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { if (method.isAnnotationPresent(RequireLogin.class) && !userContext.isLoggedIn()) { throw new UnauthorizedException("请先登录"); } return method.invoke(target, args); } }

当然实际项目中也能用Spring AOP来做这种横切逻辑，AOP本质上也依赖动态代理机制。自己手动实现一遍动态代理，对理解Spring AOP的拦截原理非常有帮助。如果你刚学Java，强烈建议手动写一个这样的Proxy案例，比只看文档理解深得多。

7.3 设计模式：策略模式解决统计维度切换

统计模块要求按时间、来源、行业这三个维度生成名片增长报表。如果把这些计算逻辑全部堆在一个类里，不仅代码长，而且加新维度时改动风险大。我用策略模式把每个维度抽成独立的策略类：

public interface StatisticStrategy { String supportDimension(); List<StatisticResult> statistic(List<CardEntity> cards); } @Component public class SourceStatisticStrategy implements StatisticStrategy { @Override public String supportDimension() { return "source"; } @Override public List<StatisticResult> statistic(List<CardEntity> cards) { return cards.stream() .collect(Collectors.groupingBy(CardEntity::getSource)) .entrySet().stream() .map(e -> new StatisticResult(e.getKey().getDisplayName(), e.getValue().size())) .collect(Collectors.toList()); } }

调用的时候根据前端传入的dimension从Spring容器里取对应的策略Bean。这样加新的统计维度时，只需新增一个实现了StatisticStrategy的类，与其他策略零耦合。设计模式这个主题在面试里经常被吐槽“八股”，但真正写项目时会发现这些模式不是为了套而套，而是为了解决真实的问题。

8. 名片排序与搜索：冒泡、快排和查找算法的工程化思考

8.1 冒泡排序：教学价值大于实际价值

冒泡排序在名片系统里有没有实际使用场景？说实话，没有。名片列表的排序我一直用Stream的sorted()，底层是JDK的TimSort。但我还是把冒泡排序写了一遍，不是为了用，而是为了在面试和教学中能讲清楚为什么它不适合大数据量。

冒泡排序的时间复杂度是O(n^2)，在名片只有几千条时可能感受不到差距，但一旦到几万条，冒泡的耗时就会明显拉胯。我用一万条测试数据做过对比：冒泡排序耗时约120ms，快速排序约15ms，JDK排序约8ms。差距非常清楚。

public static void bubbleSort(List<CardEntity> list) { int n = list.size(); for (int i = 0; i < n - 1; i++) { boolean swapped = false; for (int j = 0; j < n - 1 - i; j++) { if (list.get(j).getUpdatedAt() .isAfter(list.get(j + 1).getUpdatedAt())) { Collections.swap(list, j, j + 1); swapped = true; } } if (!swapped) { break; } } }

加了swapped标志位之后，如果某轮没有任何交换，说明已经有序，可以提前退出。这个优化在近乎有序的数据上表现很不错。如果你在面试中被问到“冒泡排序怎么优化”，这个提前退出就是最常见的答案。

8.2 快速排序：原理与实现

快速排序几乎是Java面试必考内容，我借这次项目把它完整实现并运用到了测试数据集的排序逻辑里。

快速排序的核心思想是分治：选择一个基准值（pivot），把小于基准值的元素放左边，大于基准值的放右边，然后对左右两个子区间递归排序。

public static void quickSort(int[] arr, int left, int right) { if (left >= right) return; int pivotIndex = partition(arr, left, right); quickSort(arr, left, pivotIndex - 1); quickSort(arr, pivotIndex + 1, right); } private static int partition(int[] arr, int left, int right) { int pivot = arr[right]; int i = left - 1; for (int j = left; j < right; j++) { if (arr[j] <= pivot) { i++; swap(arr, i, j); } } swap(arr, i + 1, right); return i + 1; }

这个partition方式是“Lomuto分区”，实现简单、思路清晰，但要注意在数组本身有序的情况下，快速排序会退化成O(n^2)。这也是为什么JDK里没有直接用裸的快排，而是用了TimSort这种混合排序。工程上做排序时，除非你自己清楚数据分布，否则直接使用语言内置排序是最稳妥的。

8.3 排序在页面端与算法的一致性

页面端名片列表需要支持多种排序方式：按最近更新时间、按姓名拼音、按添加时间。这个功能放在数据库里用ORDER BY也能做，但当数据做了Redis缓存之后，每次排序都走后端查询，对缓存不太友好。

这里我采用了“缓存全量列表 + 内存排序”的方案。每次列表查询先从Redis读取全量名片ID和简化信息，然后在内存中用不同的Comparator排序，最后分页返回。因为名片量一般都在几千到几万，内存排序的性能完全可以接受。

List<CardEntity> cards = cacheService.getCardList(); Comparator<CardEntity> comparator = switch (sortKey) { case "updated" -> Comparator.comparing(CardEntity::getUpdatedAt).reversed(); case "name" -> Comparator.comparing(CardEntity::getName); case "created" -> Comparator.comparing(CardEntity::getCreatedAt).reversed(); default -> Comparator.comparing(CardEntity::getId); }; cards.sort(comparator);

Java 17的switch表达式让这段代码非常简洁，这也是我选Java 17的一个重要原因。注意这里如果直接用list.sort(comparator)会修改原缓存对象，所以我在进入这一层之前已经做了copy，避免并发情况下缓存数据被意外排序。

9. 真实踩坑记录：环境问题、内存溢出与运行时异常排查

9.1 环境变量配置与版本残留问题

这个坑很多Java新手都遇到过。明明安装的是JDK 17，但cmd里java -version显示的是1.8。当时排查步骤是：先输入where java查看系统实际使用的是哪个路径下的java.exe，结果发现是别的地方安装的旧JDK。原因就是PATH里旧路径写在了前面。彻底解决的办法是移除PATH里旧JDK的bin项，并在环境变量里配置JAVA_HOME作为统一入口。

另一个相关问题是“uncaught exception java.lang.NoClassDefFoundError: java/applet/Applet”。这个问题出现在我做二维码扫描联动测试时，某些老第三方库引用了已经被移除的Applet API，JDK 17已经不支持Applet。解决办法是找到使用Applet的依赖，排除或升级它。

9.2 NoClassDefFoundError、Lombok与JDK版本的兼容性

除了Applet，还有一个典型的NoClassDefFoundError和sun.misc有关。项目里某个老版本的工具类引用了sun.misc包下的类，比如sun.misc.BASE64Encoder，这在JDK 9之后已经被移除了，导致的报错信息往往让人一头雾水。

而Lombok的报错“you aren't using a compiler supported by lombok, so lombok will not work”也属于典型的版本兼容问题。这个报错通常意味着Lombok版本过旧，不支持当前JDK版本。Lombok是编译期注解处理器，它需要适配不同版本的JDK内部API，JDK版本太新而Lombok版本太老就会出现这个问题。解决方式是升级到支持JDK 17的Lombok版本，我用的是1.18.30，问题解决。

这类问题最关键的不是背命令，而是建立一套排查思路：先看完整的异常栈，确认是哪个类抛出的异常，再查这个类属于哪个依赖，最后去查这个依赖和当前JDK版本的兼容性。大多数版本兼容问题都能按这个链路定位到。

9.3 OutOfMemoryError: insufficient memory

Excel导入大量名片数据时，JVM直接抛出OutOfMemoryError: insufficient memory。原因是POI的Workbook对象会把整个Excel文件加载到内存，而且系统默认堆内存比较小。

解决方案有两个层面。第一个层面是提高JVM堆内存，启动参数加上 -Xms512m -Xmx2g。第二个层面是使用POI的SXSSFWorkbook或者按批读取，避免一次性加载所有行。另外还要检查代码里有没有大对象没有及时释放引用。经过优化后，导入10万行数据的内存占用从大约1.2G降到400M以内。

还有一个比较隐蔽的原因是元空间不足，大量使用反射生成代理类时会出现Metaspace溢出。我在用CGLIB生成代理类的统计场景中遇到过，解决办法是适当增加 -XX:MaxMetaspaceSize。

9.4 JavaBean序列化问题：大写字母开头的变量变小写

前面提到过，我在实体类里定义了一个字段叫URL，结果在JSON序列化时变成了“url”。这个问题的根因是JavaBeans规范。因为getter方法叫getURL()，在JavaBeans内省机制中，它会解析成属性名“URL”，而Jackson等JSON库有自己的命名策略，通常按照字段名或getter名解析时会把连续大写字母处理成首字母小写形式，导致“URL”变成“url”。

解决这个问题的方案有三种：一是改字段名，不要使用全大写缩写；二是在字段上使用@JsonProperty("URL")指定序列化名称；三是在getter方法上加@JsonIgnore，再自定义一个getUrl方法。我最后选择了改字段名的方式，因为这种缩写命名在团队协作里也容易产生歧义。

9.5 数组越界与循环边界

名片系统里做分页时，我写过一段从List截取子列表的代码，容易出现数组越界问题。原因很简单，start和end的边界没有做裁剪：

int start = Math.min(page * size, list.size()); int end = Math.min((page + 1) * size, list.size()); List<CardEntity> pageList = list.subList(start, end);

其实Java的List.subList踩的坑更多是修改原列表时子列表行为异常，或者对子列表的修改影响到了原列表。正确做法是new ArrayList<>(list.subList(start, end))，切断引用关系。

数组越界异常在Java面试里属于非常基础的问题，但在实际项目中，最常见的触发场景往往是这种边界计算失误，而不是什么高深的内存布局问题。用Math.min做边界裁剪是一个简单有效的手段。

10. 写在最后：写完整套名片系统后的几点体会

整个“易卡随行”项目写下来，我最深的体会是：纸上得来终觉浅，绝知此事要躬行。很多概念在面试题里看一百遍，不如在实际项目里踩一次坑。比如Redis的increment序列化问题、JPA的N+1查询、分布式锁的过期释放问题——这些如果不落地到真实场景，很难真正理解它们的边界在哪里。

我在做项目时还有一个习惯，就是每天把当天解决的问题整理到笔记里，包括报错信息、排查链路、最终方案。这些内容后来变成了很好的面试素材，面试官问“你项目里有没有遇到什么难点”的时候，不需要背概念，直接讲故事，可信度完全不同。

这个项目后续我计划做三个方向：一是接入OCR名片识别，拍一张名片直接自动录入；二是用图数据库做社交关系分析，看看名片之间的共同联系人关系；三是做一个微信小程序端，解决移动场景下的扫码交换问题，毕竟我第一版做的Web管理后台在手机上用还是不够顺手。

如果你正在学Java，或者正准备做一个自己的完整项目，我的建议是：不要光看教程，动手做一个能解决自己实际问题的工具。名片管理只是其中一个很小的切入点，你完全可以从自己的需求出发，做一套记账工具、做一套订阅管理工具，过程和这里的思路都差不多。遇到报错不要慌，先看日志，再查资料，然后尝试复现，这套排查方法才是项目里最值钱的能力。