3个关键步骤搞定交往瓶最佳实践

刚接手一个老项目，控制台直接炸出一堆红色报错。StackTrace 长得像天书，行号指向不明，变量名全是下划线。那种感觉就像被蒙住眼睛在雷区跳舞，每一步都心惊胆战。别慌，这种“报错一堆看不懂”的困境，往往不是因为代码逻辑有多复杂，而是缺少一套清晰的排查与构建规范。

今天咱们不整虚的，直接上手一个名为“交往瓶”的实战项目。这个名字听起来有点文艺，其实它代表的是后端系统中极其常见的“多对多关联数据同步”场景。我们将用它来拆解如何从零搭建一个结构清晰、易调试的服务端模块。这里的核心不是教你怎么谈恋爱，而是教你如何用最佳实践去处理那些让你头秃的堆栈追踪。

项目目标

咱们先对齐一下颗粒度。很多初学者一上来就写 new，结果代码写了一半发现数据结构不对，全得推倒重来。做“交往瓶”这个模块，我们的目标非常明确：

解耦存储与逻辑：将用户与用户的“交往关系”独立存储，不直接挂在用户表里，避免数据库字段爆炸。
可观测性：任何一次关系变更（建立、解除、查询），都必须有清晰的日志和状态码，让 StackTrace 变成“指路明灯”而不是“迷宫”。
幂等性设计：网络抖动导致请求重复发送时，系统不能出错。这是最佳实践中极其重要的一环。

你可能会问，为什么叫“交往瓶”？因为在图论或者社交网络模型里，两个节点（用户）之间的连线（关系），就像瓶子里装的水，需要容器来承载。我们这里用一张中间表 relation_bottle 来承载这种双向或单向的关系状态。

目录结构

在敲第一行代码前，先看目录。乱改目录结构是新手最容易犯的错，导致后续引用路径全是坑。

project-root/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── bottle/
│   │   │               ├── BottleApplication.java   # 启动类
│   │   │               ├── controller/
│   │   │               │   └── RelationController.java
│   │   │               ├── service/
│   │   │               │   ├── RelationService.java
│   │   │               │   └── impl/
│   │   │               │       └── RelationServiceImpl.java
│   │   │               ├── repository/
│   │   │               │   └── RelationRepository.java
│   │   │               ├── model/
│   │   │               │   ├── User.java
│   │   │               │   └── Relation.java
│   │   │               └── exception/
│   │   │                   └── GlobalExceptionHandler.java
│   │   └── resources/
│   │       └── application.yml
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── bottle/
│                       └── RelationServiceTest.java
└── pom.xml

注意 exception 包。很多项目里没有这个，导致一旦报错，前端拿到的是 500 和一堆英文堆栈。有了全局异常处理，我们能统一捕获并返回人类可读的错误信息，这是解决“报错看不懂”的第一步。

核心代码实现

1. 数据模型：定义“瓶子”

我们先定义 Relation 实体。这里有一个最佳实践：不要只用 ID，要加上状态和时间戳。

package com.example.bottle.model;import javax.persistence.*;
import java.time.LocalDateTime;@Entity
@Table(name = "relation_bottle")
public class Relation {@Id@GeneratedValue(strategy = GenerationType.IDENTITY)private Long id;// 发起方用户ID@Column(nullable = false)private Long fromUserId;// 接收方用户ID@Column(nullable = false)private Long toUserId;// 关系状态：0-待确认, 1-已交往, 2-已解除@Column(nullable = false)private Integer status;// 创建时间，用于排查时序问题@Column(nullable = false)private LocalDateTime createTime;// 最后更新时间@Column(nullable = false)private LocalDateTime updateTime;// 构造函数，避免无参构造带来的空指针风险public Relation(Long fromUserId, Long toUserId, Integer status) {this.fromUserId = fromUserId;this.toUserId = toUserId;this.status = status;this.createTime = LocalDateTime.now();this.updateTime = LocalDateTime.now();}// Getters and Setters omitted for brevity
}

逐行讲解：

@Table(name = "relation_bottle")：明确表名，避免默认命名带来的混淆。
status 字段：这是关键。很多新手直接用“存在即交往，不存在即分手”，这会导致无法追踪历史状态。一旦有了状态机，当 StackTrace 指向“状态非法”时，你立刻知道是逻辑跳转出了问题，而不是数据丢了。
createTime：在排查并发问题时，时间戳是最好的线索。

2. Repository：数据访问层

使用 Spring Data JPA 的 Repository。这里我们要写一个自定义查询，防止 N+1 问题。

package com.example.bottle.repository;import com.example.bottle.model.Relation;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.Optional;public interface RelationRepository extends JpaRepository<Relation, Long> {// 查询两个用户之间是否已存在“有效”的关系（状态为0或1）// 注意：这里排除了状态为2（已解除）的记录，避免重复建立关系@Query("SELECT r FROM Relation r WHERE (r.fromUserId = :uid1 AND r.toUserId = :uid2 AND r.status IN (0, 1)) OR (r.fromUserId = :uid2 AND r.toUserId = :uid1 AND r.status IN (0, 1))")Optional<Relation> findActiveRelationBetween(@Param("uid1") Long uid1, @Param("uid2") Long uid2);
}

避坑点：如果不加 status IN (0, 1) 的判断，用户分手后再请求交往，系统可能会找到那条 status=2 的旧记录，导致逻辑判断错误。这是典型的“脏数据”干扰，也是 StackTrace 难以定位的原因——代码逻辑没错，但数据状态你没考虑全。

3. Service：核心业务逻辑

这里是重灾区。我们将采用“先查后改”的策略，并加上事务控制。

package com.example.bottle.service.impl;import com.example.bottle.exception.GlobalExceptionHandler;
import com.example.bottle.model.Relation;
import com.example.bottle.repository.RelationRepository;
import com.example.bottle.service.RelationService;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;import java.time.LocalDateTime;@Service
public class RelationServiceImpl implements RelationService {private final RelationRepository relationRepository;public RelationServiceImpl(RelationRepository relationRepository) {this.relationRepository = relationRepository;}@Override@Transactionalpublic Relation establishRelation(Long userId1, Long userId2) {// 1. 参数校验：防止空指针if (userId1 == null || userId2 == null) {throw new IllegalArgumentException("用户ID不能为空");}// 2. 自环检查：自己不能和自己交往if (userId1.equals(userId2)) {throw new IllegalArgumentException("不能与自己建立关系");}// 3. 查询是否存在活跃关系// 这里的 findActiveRelationBetween 会自动处理 A->B 或 B->A 的情况Relation existingRelation = relationRepository.findActiveRelationBetween(userId1, userId2).orElse(null);if (existingRelation != null) {// 如果已存在，直接返回现有关系，保证幂等性// 这是最佳实践：重复请求不报错，不重复插入return existingRelation;}// 4. 创建新关系，初始状态设为“待确认”Relation newRelation = new Relation(userId1, userId2, 0);// 5. 保存return relationRepository.save(newRelation);}@Override@Transactionalpublic Relation confirmRelation(Long relationId) {// 1. 查找关系Relation relation = relationRepository.findById(relationId).orElseThrow(() -> new RuntimeException("关系不存在: ID=" + relationId));// 2. 状态机校验// 只有“待确认”状态才能转为“已交往”if (relation.getStatus() != 0) {throw new IllegalStateException("当前状态不允许确认: 状态=" + relation.getStatus());}// 3. 更新状态relation.setStatus(1);relation.setUpdateTime(LocalDateTime.now());// 4. 保存return relationRepository.save(relation);}
}

深度解析：

幂等性：在 establishRelation 中，如果发现关系已存在，直接返回。这意味着，即使前端因为网络超时重试了 5 次，数据库里也只有一条记录。当 StackTrace 报出 DuplicateKeyException 时，往往是因为缺乏这种幂等保护。
状态机校验：confirmRelation 中严格检查 status。如果用户直接调用确认接口，但关系还没建立，或者已经分手了，这里会抛出 IllegalStateException。这种明确的业务异常，比 NullPointerException 好排查一万倍。
事务注解：@Transactional 确保“查”和“改”是一个原子操作。在高并发下，如果没有事务，两个请求可能同时查到“无关系”，然后同时插入，导致数据错乱。

运行与测试

代码写完了，怎么验证？别只点“Run”，那叫自嗨。我们要用单元测试来模拟 StackTrace 场景。

在 RelationServiceTest.java 中，我们写一个测试用例，模拟并发冲突。

package com.example.bottle;import com.example.bottle.model.Relation;
import com.example.bottle.repository.RelationRepository;
import com.example.bottle.service.impl.RelationServiceImpl;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.DirtiesContext;import static org.junit.jupiter.api.Assertions.*;@SpringBootTest
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
class RelationServiceTest {@Autowiredprivate RelationService relationService;@Autowiredprivate RelationRepository relationRepository;@Testvoid testIdempotencyOfEstablishRelation() {Long userA = 1001L;Long userB = 1002L;// 第一次建立Relation r1 = relationService.establishRelation(userA, userB);assertNotNull(r1);assertEquals(0, r1.getStatus());// 第二次建立（模拟重复请求）Relation r2 = relationService.establishRelation(userB, userA); // 注意方向反了// 断言：两次返回的应该是同一条数据库记录assertEquals(r1.getId(), r2.getId());// 验证数据库中只有一条记录long count = relationRepository.count();assertEquals(1, count);}
}

测试要点：

@DirtiesContext：确保每个测试方法结束后重置上下文，避免测试之间互相污染。
方向反转：测试中故意把 userA, userB 和 userB, userA 都试一遍。如果我们的查询逻辑只写了 from=A and to=B，这里就会失败。这就是最佳实践中提到的“全面覆盖”。
断言 count：这是最直接的证据。如果这里断言失败，说明幂等性没做好，生产环境就会堆满垃圾数据。

优化扩展

基础功能跑通了，但生产环境是复杂的。这里有两个进阶技巧，能极大提升系统的健壮性。

1. 全局异常处理：让 StackTrace 说话

我们在 exception 包下创建 GlobalExceptionHandler.java。

package com.example.bottle.exception;import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;import java.time.LocalDateTime;@RestControllerAdvice
public class GlobalExceptionHandler {// 处理业务异常@ExceptionHandler(IllegalStateException.class)public ErrorResponse handleIllegalState(IllegalStateException ex) {return new ErrorResponse(400, "业务状态错误", ex.getMessage(), LocalDateTime.now());}// 处理参数异常@ExceptionHandler(IllegalArgumentException.class)public ErrorResponse handleIllegalArgument(IllegalArgumentException ex) {return new ErrorResponse(400, "参数错误", ex.getMessage(), LocalDateTime.now());}// 兜底异常@ExceptionHandler(Exception.class)public ErrorResponse handleGeneral(Exception ex) {// 生产环境严禁返回 ex.getMessage()，防止泄露敏感信息// 这里为了演示，保留信息。实际应记录日志并返回通用错误return new ErrorResponse(500, "系统内部错误", "未知异常", LocalDateTime.now());}// 响应实体public static class ErrorResponse {public int code;public String error;public String message;public LocalDateTime timestamp;public ErrorResponse(int code, String error, String message, LocalDateTime timestamp) {this.code = code;this.error = error;this.message = message;this.timestamp = timestamp;}}
}

核心价值：当 StackTrace 指向 GlobalExceptionHandler 时，你知道是业务逻辑抛出的异常。当它指向 handleGeneral 时，你知道是意料之外的 Bug。这种分类，让排错效率提升 50%。

2. 索引优化

在 Relation 表上，我们必须加复合索引。

-- 在数据库执行
CREATE INDEX idx_relation_active ON relation_bottle (from_user_id, to_user_id, status);

为什么？因为我们的查询条件是 from_user_id = ? AND to_user_id = ? AND status IN (0, 1)。没有这个索引，全表扫描在百万级数据下会直接拖垮数据库。这也是为什么有时候代码没报错，但接口响应慢得像蜗牛——那是数据库在喊疼。

3. 参考开源实现

如果你想看更复杂的图关系处理，可以去 GitHub 看看 neo4j 的 Java Driver 源码，或者搜索 spring-social 的相关实现。很多 GitHub 开源仓库在处理“社交关系”时，会引入 Redis 缓存热点数据。虽然本篇为了简单没加缓存，但在高并发场景下，最佳实践一定是“数据库保底 + Redis 加速”。