G1 是一款专为配备多颗处理器及大容量内存的服务端机器量身打造的收集器。它的终极目标是：在极高概率满足设定的 GC 停顿时间要求的同时，依然维持高吞吐量的性能特征。 要想彻底搞懂 G1，我们需要从它的四大核心特点、特殊的内存布局，以及它独有的两种回收模式来层层剖析。

一、 G1 的四大核心基石​

G1 能够取代 CMS，主要归功于它在设计上的四个维度的全面进化：

1. 并行与并发：G1 能充分压榨多核 CPU 的硬件优势。在需要 STW（Stop-The-World）的阶段，它使用多个 GC 线程并行工作来缩短停顿时间；而在耗时最长的标记阶段，G1 能让 GC 线程与 Java 用户线程并发执行。
2. 保留分代收集，但打破物理隔离：G1 不需要其他收集器配合就能独立管理整个堆内存。它依然保留了新生代（Eden/Survivor）和老年代的概念，但在物理上，这些代不再是连续的内存块。
3. 空间整合（告别内存碎片）：

• 从整体看：G1 是基于“标记-整理”算法实现的，不会产生内存碎片。
• 从局部看（两个 Region 之间）：它是基于“标记-复制”算法实现的。这就保证了 G1 运行期间能提供规整的可用内存，极大降低了因为分配大对象找不到连续空间而被迫触发 Full GC 的概率。

4. 可预测的停顿模型（最大杀手锏）：G1 允许使用者明确指定一个目标：期望每次垃圾回收的最大暂停时间不能超过 N 毫秒（通过参数 -XX:MaxGCPauseMillis=n 配置，默认 200ms）。G1 会在后台建立时间预测模型，尽可能地保证在这个时间限制内完成回收。

二、 内存布局：化整为零的 Region 设计​

为了实现“可预测的停顿”，G1 彻底颠覆了传统的内存布局。

它将整个 Java 堆划分为了数千个大小相等的独立区域——Region。 每一个 Region 都可以根据需要，动态地扮演 Eden 区、Survivor 区 或 Old（老年代）区。此外，G1 还专门设计了一种 Humongous 区，用于专门存储体积庞大的大对象（大小超过一个 Region 容量 50% 的对象）。

这种“把内存化整为零”的设计，让 G1 能够以 Region 为最小回收单元，避免了每次都去扫描和清理整个堆。

三、 G1 的两种核心回收模式​

结合文档中的深入剖析，G1 实际的运行绝不是简单的“一刀切”，而是主要分为两种回收方式：Young GC（年轻代回收） 和 Mixed GC（混合回收）。

1. Young GC（年轻代回收）​

当新生代（主要是 Eden 区）的内存占比达到阈值（最大默认 60%），无法再为新对象分配空间时，就会触发 Young GC。这个过程会发生短暂的 STW。

微观执行流程：

1. 触发与标记：新创建的对象都在 Eden 区。触发 GC 后，G1 首先会标记出 Eden 和 Survivor 区域中的所有存活对象。
2. 动态筛选与复制：这是 G1 最智能的地方！G1 在后台会记录以往每次回收 Eden 和 Survivor 区的平均耗时。

举个硬核的例子： 假设你配置了 -XX:MaxGCPauseMillis=200（最大停顿 200ms），而 G1 历史统计得出回收一个 Region 平均需要 40ms。那么 G1 经过精确计算，这次回收最多只能回收 4 个 Region（40ms * 4 = 160ms < 200ms），以保证不违背停顿时间的承诺。

3. 转移与清空：根据计算出的数量，G1 选择部分 Region，将里面的存活对象复制到一个新的 Survivor 区中（并且对象年龄 +1），然后直接清空原来的旧 Region 区域。后续的 Young GC 会不断重复这个过程，直到对象年龄达标晋升到老年代。

2. 混合回收（Mixed GC）的四大步骤​

当老年代的堆空间占用达到一定阈值（默认 45%）时，会触发并发标记周期，并最终进入 Mixed GC 阶段。Mixed GC 不仅回收整个年轻代，还会回收部分老年代。

它的运作大致分为以下四个经典步骤：

1. 初始标记（Initial Mark）：短暂停顿（STW）。仅仅标记从 GC Roots 能直接引用的活跃对象。由于通常借用 Young GC 的 STW 同步完成，所以速度极快。
2. 并发标记（Concurrent Mark）：与应用并发运行。从 GC Roots 的直接引用开始，扫描整个堆，标记所有可达对象。耗时较长，但不会阻塞用户线程。
3. 最终标记（Final Mark / Remark）：短暂停顿（STW）。处理并发标记期间，因为用户线程继续运行而导致引用关系发生变化的残留对象（G1 这里使用的是 SATB 算法）。
4. 筛选回收（Cleanup / Evacuation）：短暂停顿（STW）。这是体现 Garbage-First（垃圾优先） 名字由来的核心阶段！

• G1 会根据之前并发标记的结果，计算每个 Region 的垃圾占比。
• 它在后台维护了一个优先列表，根据用户允许的收集时间（MaxGCPauseMillis），优先选择回收价值最大（垃圾最多、存活对象最少）的老年代 Region 进行回收。
• 把选中 Region 中的存活对象复制到新区域，然后清空旧区域。

四、 G1 的代价与局限性​

世界上没有免费的午餐，G1 为了实现这种高效率和可预测性，也付出了不小的底层代价：

• 极高的内存占用：为了解决 Region 之间的跨代引用问题，每个 Region 必须维护一个叫 Remembered Set (RSet) 的数据结构，记录“谁引用了我”。在堆被切成几千个 Region 的情况下，G1 收集器维护这些 RSet 需要消耗堆内存容量的 10% ~ 20%。
• CPU 负载负担：为了在并发运行时维护复杂的 RSet 更新，G1 在给对象赋值的底层操作中加入了写屏障（Write Barrier），这些额外的计算逻辑会消耗更多的 CPU 资源。

总结： G1 的出现，完美诠释了“以空间换时间”和“化整为零”的架构哲学。它通过精确掌控 Region 的回收收益和耗时，让 Java 终于拥有了一款在吞吐量与低延迟之间取得极佳平衡的现代垃圾收集器。

在社交、O2O 等业务中，"查找附近的人" 是一个高频场景。大部分开发者第一反应是使用 Redis 从 3.2 版本引入的 GEO 数据结构。

使用 GEOADD 写入坐标，使用 GEOSEARCH（或旧版的 GEORADIUS）按距离搜索，看起来一切都很完美。但当产品经理提出新需求时——

"不仅要离得近，还要优先展示最近活跃过的用户（距离 + 活跃度混合排序）"

技术痛点就出现了。

为什么 Redis GEO 做不到？​

Redis GEO 底层的本质是 ZSET（有序集合）。它利用 GeoHash 算法将二维经纬度转化为一维的 52 位整数，并强行占用了 ZSET 唯一的 Score 字段来存储这个整数。

┌─────────────────────────────────────────────────┐
│              Redis GEO 底层结构                   │
│                                                   │
│   ZSET Key: "nearby_users"                        │
│   ┌──────────┬──────────────────────────┐         │
│   │  Member  │   Score (GeoHash 值)      │         │
│   ├──────────┼──────────────────────────┤         │
│   │  user:1  │  4054421060663041        │  ← 经纬度编码后的整数 │
│   │  user:2  │  4054421060812801        │  ← 被 GeoHash 占了！ │
│   │  user:3  │  4054421061038081        │  ← 没位置放活跃度了   │
│   └──────────┴──────────────────────────┘         │
│                                                   │
│   ❌ Score 已被占用，无法再存第二个排序字段         │
└─────────────────────────────────────────────────┘

所以，Redis 的原生 GEO 命令只能按距离排序，根本无法传入第二个业务字段（如活跃度）进行联合排序。

面对这个限制，业界通常有两套架构演进方案。

方案一：经典架构 ——「粗排召回 + 内存精排」（应用层计算）​

这是在不升级现有标准版 Redis 基础设施的情况下，最成熟、落地最广的架构方案。

核心思想是：把 Redis 当作「召回引擎」，把 Java 业务服务当作「精排引擎」。

1. 架构流程图​

┌──────────┐      ①请求20条        ┌──────────────────┐
│          │ ──────────────────────▶ │   Java 应用服务   │
│  客户端   │                        │                    │
│          │ ◀────────────────────── │  ⑤ 返回Top20       │
└──────────┘      精排后的20条       └─────┬──────┬───────┘
                                         │      │
                            ②GEOSEARCH   │      │ ③HMGET
                            召回200条     │      │ 批量查活跃度
                                         ▼      ▼
                                   ┌──────────────────┐
                                   │      Redis        │
                                   │                    │
                                   │  GEO: 坐标数据     │
                                   │  HASH: 活跃度数据  │
                                   └──────────────────┘
                                         │
                            ④ Java 内存中进行
                            归一化 + 加权计算 + 排序

整个流程分为 5 步：

1. 扩大召回池 (Recall)：客户端请求 20 条数据，后端向 Redis 请求 200 条（适度放大 10 倍的召回量）。
2. 批量获取活跃度 (Batch Fetch)：拿到 200 个用户 ID 后，通过 Pipeline 批量从 Hash 中查出活跃度得分。
3. 归一化计算 (Normalize)：将距离和活跃度分别映射到 [0, 1] 区间，消除量纲差异。
4. 加权打分 (Rerank)：配合业务权重（如距离 60%，活跃度 40%）计算综合分。
5. 截断返回 (Truncate)：按综合分降序排列，截取 Top 20 返回前端。

2. Mock 数据准备​

假设当前用户"我"的坐标是 北京天安门 (116.404, 39.915)，我们先往 Redis 灌入一批模拟用户数据：

# ============ 第一步：写入用户坐标到 GEO ============
# GEOADD key longitude latitude member
GEOADD nearby:users 116.408 39.918 user:A
GEOADD nearby:users 116.398 39.910 user:B
GEOADD nearby:users 116.420 39.930 user:C
GEOADD nearby:users 116.450 39.950 user:D
GEOADD nearby:users 116.380 39.900 user:E
GEOADD nearby:users 116.410 39.916 user:F
GEOADD nearby:users 116.500 39.980 user:G
GEOADD nearby:users 116.390 39.905 user:H

# ============ 第二步：写入用户活跃度到 HASH ============
# 活跃度得分范围 [0, 100]，越高越活跃
HSET user:activity user:A 30
HSET user:activity user:B 95
HSET user:activity user:C 60
HSET user:activity user:D 85
HSET user:activity user:E 10
HSET user:activity user:F 50
HSET user:activity user:G 90
HSET user:activity user:H 75

用表格看一下这批数据：

注意观察：如果纯按距离排，user:A 排第一（最近但活跃度只有 30）；如果纯按活跃度排，user:B 排第一（活跃度 95 但距离 0.7km）。混合排序的目标就是在两者间找到平衡。

3. 完整 Java 代码实现​

3.1 核心数据模型​

/**
 * 附近用户信息（含距离和活跃度）
 */
public record NearbyUser(
    String userId,
    double distanceKm,    // 与"我"的距离（公里）
    int activityScore,    // 活跃度得分 [0, 100]
    double finalScore     // 综合打分（归一化加权后）
) {
    /**
     * 构造时不传 finalScore，后续计算后赋值
     */
    public NearbyUser(String userId, double distanceKm, int activityScore) {
        this(userId, distanceKm, activityScore, 0.0);
    }

    public NearbyUser withFinalScore(double score) {
        return new NearbyUser(userId, distanceKm, activityScore, score);
    }
}

3.2 召回 + 精排服务​

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.geo.*;
import org.springframework.data.redis.connection.RedisGeoCommands;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

import java.util.*;
import java.util.stream.Collectors;

@Slf4j
@Service
@RequiredArgsConstructor
public class NearbyUserService {

    private final StringRedisTemplate redisTemplate;

    /** GEO Key */
    private static final String GEO_KEY = "nearby:users";
    /** 活跃度 Hash Key */
    private static final String ACTIVITY_KEY = "user:activity";
    /** 召回倍率：请求 N 条 → 召回 N * RECALL_RATIO 条 */
    private static final int RECALL_RATIO = 10;
    /** 排序权重 */
    private static final double WEIGHT_DISTANCE = 0.6;
    private static final double WEIGHT_ACTIVITY = 0.4;

    /**
     * 查询附近的人（距离 + 活跃度混合排序）
     *
     * @param myLon       我的经度
     * @param myLat       我的纬度
     * @param radiusKm    搜索半径（公里）
     * @param pageSize    需要返回的条数
     * @return 混合排序后的用户列表
     */
    public List<NearbyUser> findNearbyUsers(double myLon, double myLat,
                                            double radiusKm, int pageSize) {
        // ============ Step 1: 扩大召回 ============
        int recallCount = pageSize * RECALL_RATIO;

        // 构造搜索参数：按距离升序，限制召回数量
        RedisGeoCommands.GeoSearchCommandArgs args = RedisGeoCommands
                .GeoSearchCommandArgs.newGeoSearchArgs()
                .includeDistance()     // 返回距离
                .sortAscending()      // 距离近的优先
                .limit(recallCount);  // 限制召回数量

        GeoResults<RedisGeoCommands.GeoLocation<String>> geoResults =
                redisTemplate.opsForGeo().search(
                        GEO_KEY,
                        GeoReference.fromCoordinate(myLon, myLat),
                        new Distance(radiusKm, Metrics.KILOMETERS),
                        args
                );

        if (geoResults == null || geoResults.getContent().isEmpty()) {
            log.info("召回阶段：半径 {}km 内未找到用户", radiusKm);
            return Collections.emptyList();
        }

        List<GeoResult<RedisGeoCommands.GeoLocation<String>>> results =
                geoResults.getContent();
        log.info("召回阶段：半径 {}km 内召回 {} 个用户", radiusKm, results.size());

        // ============ Step 2: 批量获取活跃度 ============
        List<String> userIds = results.stream()
                .map(r -> r.getContent().getName())
                .toList();

        // 使用 HMGET 一次网络往返拿到所有活跃度
        List<Object> activityScores = redisTemplate.opsForHash()
                .multiGet(ACTIVITY_KEY, Collections.unmodifiableList(userIds));

        // 组装 Map<userId, activityScore>
        Map<String, Integer> activityMap = new HashMap<>();
        for (int i = 0; i < userIds.size(); i++) {
            Object raw = activityScores.get(i);
            int score = (raw != null) ? Integer.parseInt(raw.toString()) : 0;
            activityMap.put(userIds.get(i), score);
        }

        // ============ Step 3: 构建候选列表 ============
        List<NearbyUser> candidates = results.stream()
                .map(r -> new NearbyUser(
                        r.getContent().getName(),
                        r.getDistance().getValue(),
                        activityMap.getOrDefault(r.getContent().getName(), 0)
                ))
                .toList();

        // ============ Step 4: 归一化 + 加权打分 ============
        return rerank(candidates, pageSize);
    }

    /**
     * 精排：归一化 + 加权 + 截断
     */
    private List<NearbyUser> rerank(List<NearbyUser> candidates, int pageSize) {
        if (candidates.isEmpty()) {
            return Collections.emptyList();
        }

        // --- 4.1 找出距离和活跃度的最大最小值 ---
        double maxDist = candidates.stream()
                .mapToDouble(NearbyUser::distanceKm).max().orElse(1.0);
        double minDist = candidates.stream()
                .mapToDouble(NearbyUser::distanceKm).min().orElse(0.0);
        int maxActivity = candidates.stream()
                .mapToInt(NearbyUser::activityScore).max().orElse(1);
        int minActivity = candidates.stream()
                .mapToInt(NearbyUser::activityScore).min().orElse(0);

        double distRange = (maxDist - minDist) == 0 ? 1.0 : (maxDist - minDist);
        double actRange = (maxActivity - minActivity) == 0 ? 1.0 : (maxActivity - minActivity);

        // --- 4.2 归一化 + 加权计算 ---
        // 距离：越近得分越高 → distScore = 1 - (dist - minDist) / distRange
        // 活跃度：越高得分越高 → actScore = (act - minActivity) / actRange
        List<NearbyUser> scored = candidates.stream()
                .map(u -> {
                    double distScore = 1.0 - (u.distanceKm() - minDist) / distRange;
                    double actScore = (u.activityScore() - minActivity) / actRange;
                    double finalScore = WEIGHT_DISTANCE * distScore
                                      + WEIGHT_ACTIVITY * actScore;
                    return u.withFinalScore(finalScore);
                })
                .toList();

        // --- 4.3 按 finalScore 降序排列，截断返回 ---
        return scored.stream()
                .sorted(Comparator.comparingDouble(NearbyUser::finalScore).reversed())
                .limit(pageSize)
                .collect(Collectors.toList());
    }
}

3.3 Controller 层​

import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/nearby")
@RequiredArgsConstructor
public class NearbyUserController {

    private final NearbyUserService nearbyUserService;

    /**
     * 查询附近的人
     *
     * @param lon      我的经度
     * @param lat      我的纬度
     * @param radiusKm 搜索半径，默认 10km
     * @param size     返回条数，默认 5
     */
    @GetMapping("/users")
    public List<NearbyUser> nearby(
            @RequestParam double lon,
            @RequestParam double lat,
            @RequestParam(defaultValue = "10") double radiusKm,
            @RequestParam(defaultValue = "5") int size) {
        return nearbyUserService.findNearbyUsers(lon, lat, radiusKm, size);
    }
}

4. Mock 数据走一遍全流程​

假设客户端请求：GET /api/nearby/users?lon=116.404&lat=39.915&radiusKm=10&size=3

Step 1：召回阶段​

Redis GEOSEARCH 在 10km 半径内按距离升序返回（size=3，RECALL_RATIO=10，所以召回 30 条，但我们只有 7 条在范围内）：

user:G 距离 11km，超出 10km 半径，被过滤掉了。

Step 2：批量查活跃度​

一次 HMGET user:activity user:A user:F user:B user:H user:C user:E user:D，得到：

Step 3：归一化计算​

找出最值：

• 距离：min=0.50，max=5.30，range=4.80
• 活跃度：min=10，max=95，range=85

归一化公式：

• 距离得分 = 1 - (dist - 0.50) / 4.80（越近越高）
• 活跃度得分 = (activity - 10) / 85（越活跃越高）

Step 4：加权打分（距离 60% + 活跃度 40%）​

FinalScore = 0.6 × 距离归一化 + 0.4 × 活跃度归一化

Step 5：截断 Top 3 返回​

最终返回：user:B → user:F → user:H

🔍 分析结果：

• user:A 虽然距离最近（0.50km），但活跃度太低（30），被挤到了第 4 名。
• user:B 虽然距离稍远（0.72km），但活跃度拉满（95），综合分最高，排名第一。
• user:D 虽然活跃度很高（85），但距离太远（5.3km），综合分被距离权重压低。

这就是混合排序的魅力——在"近"和"活跃"之间找到最佳平衡点。

5. 优缺点评估​

✅ 优点：

• 兼容性极强：适用于所有 3.2+ 版本的标准 Redis，不需要任何模块或升级。
• 业务极度灵活：排序逻辑在 Java 代码中，你可以随时接入更多维度（VIP 等级、同城加分、性别偏好），甚至对接推荐算法模型。权重调整只需改配置，无需改任何数据结构。

❌ 缺点：

• 网络 I/O 放大：为了拿 3 条数据，实际传输了 7 条 GEO 数据 + 7 次 HASH 查询。在百万级用户场景下，这个放大效应会很明显。
• JVM 内存压力：高并发场景下，每个请求都要在内存中创建候选列表、做排序，容易引发 GC 抖动。
• 极小概率的「漏斗效应」：如果召回池的 200 人活跃度都很低，而第 201 个人虽然远一点但活跃度极高，他会被召回阶段直接淘汰，永远不会出现在结果中。

方案二：降维打击 ——「原生多维联合索引」（存储层计算）​

0. 在讲方案之前：什么是 RediSearch？​

很多开发者对 Redis 的认知还停留在"缓存 + 简单数据结构"的阶段。但 Redis 在近几年发生了重大进化：

Redis 版本进化路线（与搜索相关）：

Redis 3.2 (2016)  ── 引入 GEO 命令
       │
Redis Modules (2017) ── 支持加载第三方模块
       │
RediSearch 1.0 (2018) ── 独立模块，需手动安装
       │
Redis Stack (2022) ── 官方整合包，内置 RediSearch + RedisJSON 等
       │
Redis 8.0 (2025) ── RediSearch 不再是模块，成为 Redis 核心的一部分！

RediSearch 做了一件什么事？

简单来说，它让 Redis 从一个"只能按 Key 查、按 Score 排"的 KV 存储，进化成了一个支持全文搜索、多条件过滤、多字段排序的内存数据库。

你可以把它类比为：给 Redis 装上了一个 Elasticsearch 级别的查询引擎，但因为数据本身就在内存里，所以比 ES 快得多。

1. 核心概念：数据与索引分离​

在传统 Redis 中，数据结构本身就是"索引"。比如 ZSET 的 Score 就是排序依据，GEO 的 GeoHash 也是排序依据。这种设计简单高效，但一个数据结构只能支撑一种排序方式。

RediSearch 引入了数据与索引分离的思想：

传统 Redis:
┌─────────────────────────────┐
│  ZSET（数据 = 索引）          │
│  Score 只能存一个值           │
│  只能按一个维度排序            │
└─────────────────────────────┘

RediSearch:
┌─────────────────────────────┐      ┌───────────────────────────┐
│  HASH / JSON（纯数据存储）    │      │  自动维护的多种索引         │
│                               │ ───▶ │                             │
│  user:1 {                     │      │  ☑ location → Quadtree     │
│    location: "116.4,39.9"     │      │  ☑ activity  → SkipList    │
│    activity: 85               │      │  ☑ nickname  → Trie 前缀树  │
│    vip_level: 3               │      │  ☑ bio       → 倒排索引     │
│  }                            │      │                             │
└─────────────────────────────┘      └───────────────────────────┘
         数据层                               索引层
      （你来写入）                       （RediSearch 自动维护）

你只需要把数据写入普通的 HASH，然后通过 FT.CREATE 命令告诉 Redis："请帮我对这些字段自动建立索引"。之后的写入、更新、删除操作，索引会自动同步更新，无需你手动维护。

2. 底层索引结构详解​

RediSearch 为不同的字段类型选择了不同的最优索引结构：

当我们执行一条联合查询时，RediSearch 在底层的工作流程如下：

查询命令:
FT.SEARCH users_idx "@location:[116.404 39.915 10 km]" SORTBY activity_score DESC

底层执行过程:

Step 1: Quadtree 范围查询
┌─────────────────────────────┐
│      四叉树空间索引            │
│                               │
│   以(116.404, 39.915)为圆心   │
│   10km 为半径                 │
│   快速剪枝，筛出候选集         │
│                               │
│   输出: {A, B, C, F, H, E, D} │  ← 7 个用户在范围内
└───────────┬─────────────────┘
            │
            ▼
Step 2: SkipList 排序
┌─────────────────────────────┐
│      跳表排序索引              │
│                               │
│   对候选集 {A,B,C,F,H,E,D}   │
│   按 activity_score 降序排列   │
│                               │
│   输出: B(95) → D(85) → H(75) │  ← 直接输出 Top 3
│         → C(60) → F(50) → ...│
└───────────┬─────────────────┘
            │
            ▼
Step 3: 回表取数据
┌─────────────────────────────┐
│   从 HASH 中取 B, D, H 的     │
│   完整数据返回给客户端         │
└─────────────────────────────┘

🔑 关键理解：整个过程全部在 Redis 的 C 语言引擎内完成，没有网络往返、没有 Java 对象创建、没有 GC。这就是所谓的"降维打击"。

3. 手把手实战：从建索引到查询​

3.1 准备数据（用普通 HASH 写入）​

# 注意：这里使用普通的 HSET 写入数据
# location 字段格式为 "经度,纬度"（逗号分隔的字符串）
HSET user:A location "116.408,39.918" activity_score 30 nickname "张三" vip_level 0
HSET user:B location "116.398,39.910" activity_score 95 nickname "李四" vip_level 2
HSET user:C location "116.420,39.930" activity_score 60 nickname "王五" vip_level 1
HSET user:D location "116.450,39.950" activity_score 85 nickname "赵六" vip_level 3
HSET user:E location "116.380,39.900" activity_score 10 nickname "孙七" vip_level 0
HSET user:F location "116.410,39.916" activity_score 50 nickname "周八" vip_level 1
HSET user:G location "116.500,39.980" activity_score 90 nickname "吴九" vip_level 2
HSET user:H location "116.390,39.905" activity_score 75 nickname "郑十" vip_level 1

3.2 创建索引​

FT.CREATE users_idx                    # 索引名称
  ON HASH                              # 索引 HASH 类型的数据
  PREFIX 1 user:                       # 只索引 Key 前缀为 "user:" 的数据
  SCHEMA                               # 定义索引字段
    location GEO                       # 地理位置字段 → 自动建 Quadtree
    activity_score NUMERIC SORTABLE    # 数值字段 → 自动建 SkipList，支持排序
    nickname TEXT                      # 文本字段 → 自动建倒排索引
    vip_level NUMERIC SORTABLE         # 数值字段 → 自动建 SkipList

💡 注意：FT.CREATE 命令执行后，Redis 会异步扫描已有数据并自动建立索引。之后新写入的 user:* 数据也会被自动索引。

3.3 执行联合查询​

# 查询1：10km 内的用户，按活跃度降序，取前 3 条
FT.SEARCH users_idx
  "@location:[116.404 39.915 10 km]"
  SORTBY activity_score DESC
  LIMIT 0 3

# 返回结果：
# 1) (integer) 7                        ← 总共命中 7 条
# 2) "user:B"                           ← 第1条
# 3) 1) "activity_score" 2) "95" 3) "nickname" 4) "李四" ...
# 4) "user:D"                           ← 第2条
# 5) 1) "activity_score" 2) "85" 3) "nickname" 4) "赵六" ...
# 6) "user:H"                           ← 第3条
# 7) 1) "activity_score" 2) "75" 3) "nickname" 4) "郑十" ...

# 查询2：5km 内 + VIP 等级 ≥ 1 的用户，按活跃度降序
FT.SEARCH users_idx
  "@location:[116.404 39.915 5 km] @vip_level:[1 +inf]"
  SORTBY activity_score DESC
  LIMIT 0 3

# 返回：user:B(VIP2,活跃95) → user:H(VIP1,活跃75) → user:C(VIP1,活跃60)

# 查询3：10km 内 + 昵称包含"六"的用户
FT.SEARCH users_idx
  "@location:[116.404 39.915 10 km] @nickname:六"

# 返回：user:D（赵六）

🎯 一条命令搞定地理过滤 + 数值过滤 + 文本搜索 + 排序 + 分页，这就是 RediSearch 的威力。

4. Java 端优雅集成（Redis OM Spring）​

手动拼 FT.SEARCH 命令太原始了。官方提供了 redis-om-spring 库，让你像写 Spring Data JPA 一样操作 RediSearch。

4.1 引入依赖​

<dependency>
    <groupId>com.redis.om</groupId>
    <artifactId>redis-om-spring</artifactId>
    <version>0.9.8</version>
</dependency>

4.2 启用 Redis OM​

import com.redis.om.spring.annotations.EnableRedisDocumentRepositories;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableRedisDocumentRepositories(basePackages = "com.example.nearby")
public class NearbyApplication {
    public static void main(String[] args) {
        SpringApplication.run(NearbyApplication.class, args);
    }
}

4.3 定义实体与索引​

import com.redis.om.spring.annotations.Document;
import com.redis.om.spring.annotations.Indexed;
import com.redis.om.spring.annotations.Searchable;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.NonNull;
import lombok.RequiredArgsConstructor;
import org.springframework.data.annotation.Id;
import org.springframework.data.geo.Point;

/**
 * 用户画像实体
 *
 * <p>注解说明：
 * - @Document：标记为 Redis 文档，底层存储为 JSON 格式
 * - @Indexed：为字段创建精确匹配/数值/地理索引
 * - @Searchable：为字段创建全文搜索索引（倒排索引）
 */
@Data
@NoArgsConstructor
@RequiredArgsConstructor(staticName = "of")
@Document(value = "user")  // Key 前缀为 "user:"，索引名自动生成
public class UserProfile {

    @Id
    @NonNull
    private String userId;

    /** 地理位置 → 自动建 GEO 索引（Quadtree） */
    @NonNull
    @Indexed
    private Point location;

    /** 活跃度得分 → 自动建 NUMERIC 索引（SkipList） */
    @NonNull
    @Indexed(sortable = true)
    private Double activityScore;

    /** 昵称 → 自动建全文搜索索引（倒排索引） */
    @Searchable
    private String nickname;

    /** VIP 等级 → 自动建 NUMERIC 索引 */
    @Indexed(sortable = true)
    private Integer vipLevel;
}

4.4 定义 Repository 接口​

import com.redis.om.spring.repository.RedisDocumentRepository;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.geo.Distance;
import org.springframework.data.geo.Point;

/**
 * 用户画像 Repository
 *
 * <p>方法名约定会被 Redis OM 自动翻译为 FT.SEARCH 命令：
 * findByLocationNear → @location:[lon lat radius km]
 * OrderByActivityScoreDesc → SORTBY activity_score DESC
 */
public interface UserProfileRepository
        extends RedisDocumentRepository<UserProfile, String> {

    /**
     * 查询指定范围内的用户，按活跃度降序分页
     * 自动翻译为：FT.SEARCH @location:[...] SORTBY activity_score DESC LIMIT ...
     */
    Page<UserProfile> findByLocationNearOrderByActivityScoreDesc(
            Point point, Distance distance, Pageable pageable);

    /**
     * 查询指定范围内 + VIP 等级大于等于指定值的用户，按活跃度降序分页
     */
    Page<UserProfile> findByLocationNearAndVipLevelGreaterThanEqualOrderByActivityScoreDesc(
            Point point, Distance distance, Integer vipLevel, Pageable pageable);
}

4.5 Service & Controller​

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.geo.Distance;
import org.springframework.data.geo.Metrics;
import org.springframework.data.geo.Point;
import org.springframework.stereotype.Service;

@Slf4j
@Service
@RequiredArgsConstructor
public class NearbyUserServiceV2 {

    private final UserProfileRepository userProfileRepository;

    /**
     * 使用 RediSearch 原生联合索引查询附近的人
     *
     * <p>对比方案一：
     * - 无需扩大召回
     * - 无需批量查活跃度
     * - 无需内存排序
     * - 一次调用直接拿到全局最优解
     */
    public Page<UserProfile> findNearbyUsers(double lon, double lat,
                                              double radiusKm, int page, int size) {
        Point myLocation = new Point(lon, lat);
        Distance searchRadius = new Distance(radiusKm, Metrics.KILOMETERS);

        return userProfileRepository
                .findByLocationNearOrderByActivityScoreDesc(
                        myLocation, searchRadius, PageRequest.of(page, size));
    }

    /**
     * 带 VIP 过滤的查询
     */
    public Page<UserProfile> findNearbyVipUsers(double lon, double lat,
                                                 double radiusKm, int minVipLevel,
                                                 int page, int size) {
        return userProfileRepository
                .findByLocationNearAndVipLevelGreaterThanEqualOrderByActivityScoreDesc(
                        new Point(lon, lat),
                        new Distance(radiusKm, Metrics.KILOMETERS),
                        minVipLevel,
                        PageRequest.of(page, size));
    }
}

import lombok.RequiredArgsConstructor;
import org.springframework.data.domain.Page;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v2/nearby")
@RequiredArgsConstructor
public class NearbyUserControllerV2 {

    private final NearbyUserServiceV2 nearbyUserService;

    @GetMapping("/users")
    public Page<UserProfile> nearby(
            @RequestParam double lon,
            @RequestParam double lat,
            @RequestParam(defaultValue = "10") double radiusKm,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "5") int size) {
        return nearbyUserService.findNearbyUsers(lon, lat, radiusKm, page, size);
    }

    @GetMapping("/vip-users")
    public Page<UserProfile> nearbyVip(
            @RequestParam double lon,
            @RequestParam double lat,
            @RequestParam(defaultValue = "10") double radiusKm,
            @RequestParam(defaultValue = "1") int minVipLevel,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "5") int size) {
        return nearbyUserService.findNearbyVipUsers(
                lon, lat, radiusKm, minVipLevel, page, size);
    }
}

5. 同样的数据，方案二的查询结果​

使用方案二查询 10km 内按活跃度降序 Top 3：

🔍 对比方案一的结果：

方案一（距离60% + 活跃度40%）：user:B → user:F → user:H 方案二（纯活跃度排序）： user:B → user:D → user:H

区别在于：方案二这里是纯按活跃度排序（SORTBY activity_score DESC），user:D 虽然距离远(5.3km)但活跃度高(85)，所以排第二。而方案一的加权公式把距离因素考虑进去了，user:D 被压到了第 6 名。

如果你也想在方案二中实现加权混合排序，可以在 HSET 时预计算一个 weighted_score 字段（定时任务更新），或使用 FT.AGGREGATE 命令在查询时动态计算（语法稍复杂，但能实现等效的加权打分）。

6. 优缺点评估​

✅ 优点：

• 性能天花板：全部计算在 Redis C 语言引擎内完成，无网络放大、无 Java GC 压力。
• 代码极其简洁：从方案一的 100+ 行精排逻辑，缩减到 1 行方法名声明。
• 全局最优解：不存在"漏斗效应"，所有在范围内的用户都会被考虑。
• 天然支持分页：LIMIT offset count 直接分页，无需在内存中手动截断。

❌ 缺点：

• 基础设施门槛：必须使用 Redis 8.0 或安装 RediSearch 模块的 Redis Stack。传统的云 Redis 实例通常不支持。
• 内存开销更大：除了数据本身，还要额外存储 Quadtree、SkipList、倒排索引等索引结构，内存占用通常是纯数据的 2~4 倍。
• 复杂加权排序受限：如果需要像方案一那样的多维加权公式，需要借助 FT.AGGREGATE + APPLY 函数，学习曲线陡峭。

📝 总结与选型建议​

方案全维度对比​

一句话总结​

如果你的系统还是传统的 Redis，用**「扩大召回 + 内存重排」**足以应付 90% 的场景；如果你准备拥抱未来或正在主导架构升级，毫不犹豫地推行 Redis 8.0 的原生联合索引，享受底层 C 语言级别的降维打击吧！

延伸阅读​

• Redis 官方文档 - GEO 命令
• RediSearch 官方文档
• Redis OM Spring GitHub
• Redis 8.0 Release Notes

本文将带你深入了解分布式锁的常见实现方案，特别是 Redis 方案的演进，以及工业级组件 Redisson 的底层原理。

1. 分布式锁的核心要求​

一个靠谱的分布式锁，通常需要满足以下条件：

1. 互斥性：在任意时刻，只能有一个客户端持有锁。
2. 防死锁：即使持有锁的客户端崩溃或网络断开，锁也能自动释放（通常通过过期时间实现）。
3. 可重入性：同一个客户端可以多次获取同一把锁。
4. 高性能/高可用：加锁和解锁需要开销小，且服务要稳定。

2. 常见的实现方案​

2.1 基于数据库（MySQL）实现​

用 MySQL 来做分布式锁，是一种非常经典的思路。它适合系统规模不大、并发量不高，且不想为了分布式锁单独引入 Redis 或 Zookeeper 的场景。

在 MySQL 中，主流的方案有两种：基于唯一索引和基于悲观锁（FOR UPDATE）。

方案一：基于唯一索引（Unique Key）​

这是最容易想到的一种方式。核心思路是：利用数据库唯一索引的约束，让多个节点竞争插入同一条记录，只有一个能成功。插入成功 = 拿到锁，删除记录 = 释放锁。

① 表结构设计

CREATE TABLE `distributed_lock` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
  `resource_name` varchar(64) NOT NULL COMMENT '锁定的资源名称',
  `owner_info` varchar(128) NOT NULL COMMENT '锁持有者信息(如 机器IP + 线程ID)',
  `create_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uidx_resource` (`resource_name`) -- 核心：唯一索引保证互斥
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='分布式锁表';

② 加锁与解锁

• 加锁：尝试插入一条带有资源名称的记录。

  INSERT INTO distributed_lock (resource_name, owner_info) 
  VALUES ('order_12345', '192.168.1.100:thread-1');

  插入成功说明拿到了锁；如果抛出 DuplicateKeyException（唯一键冲突），说明锁已被占，加锁失败。

• 解锁：业务执行完毕后，删除记录即可。

  DELETE FROM distributed_lock WHERE resource_name = 'order_12345';

③ 存在的问题

这种方案看起来简单，但在生产环境中有几个绕不开的坑：

方案二：基于悲观锁（FOR UPDATE）​

这种方案利用了 InnoDB 引擎的行级排他锁。通过 SELECT ... FOR UPDATE，MySQL 会对命中的行加上 X 锁，其他事务访问同一行时会被阻塞，直到持锁事务提交或回滚。

① 表结构设计

CREATE TABLE `distributed_lock` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `resource_name` varchar(64) NOT NULL,
  `description` varchar(255) DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uidx_resource` (`resource_name`) -- 必须有索引！
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

② 加锁与解锁

-- 1. 开启事务
BEGIN;

-- 2. 加锁：如果该行已被其他事务锁定，当前语句会阻塞等待
SELECT * FROM distributed_lock 
WHERE resource_name = 'order_12345' FOR UPDATE;

-- 3. 执行业务逻辑...

-- 4. 释放锁：提交事务，MySQL 自动释放行锁
COMMIT;

在 Spring 中，可以通过 @Transactional 注解配合 MyBatis/JPA 来实现。

③ 优势与踩坑

优势：

• 天然防死锁：如果服务宕机，数据库连接断开，MySQL 会自动回滚事务并释放行锁。不需要像方案一那样搞定时清理。
• 天然阻塞：FOR UPDATE 本身就会排队等待，不需要在代码里写重试循环。

踩坑：

• 索引失效 → 表锁：InnoDB 的行锁是基于索引实现的。如果 WHERE 条件的字段没有命中索引，行锁会退化为表锁，锁住整张表，导致所有并发请求串行化，吞吐量骤降。这是最危险的坑。
• 连接池耗尽：整个业务执行期间，数据库连接一直被占用。如果业务逻辑耗时较长，连接池会被迅速耗尽。因此必须保证加锁后的逻辑快进快出，严禁在事务中做 RPC 调用或大量 IO 操作。

MySQL 方案对比​

2.2 基于 Redis 的基础实现​

Redis 是内存数据库，性能极高，天然适合做分布式锁。我们先不谈 Redisson，来看看用原生 Redis 命令手动实现分布式锁的演进过程——理解这个过程，才能真正理解 Redisson 到底帮我们解决了什么。

版本 1.0：SETNX + EXPIRE（有致命缺陷）​

最朴素的想法：用 SETNX（SET if Not eXists）抢占一个 key，谁抢到谁就持有锁。

if (redis.setnx("lock_key", "value") == 1) {
    redis.expire("lock_key", 30); // 设置30秒过期
    try {
        // 业务逻辑
    } finally {
        redis.del("lock_key");
    }
}

版本 2.0：原子加锁（SET NX PX）​

从 Redis 2.6.12 开始，SET 命令支持参数组合，一条命令搞定加锁 + 过期：

SET lock_key unique_value NX PX 30000

对应的 Java 代码（使用 Jedis）：

String lockKey = "lock:order:12345";
String uniqueValue = UUID.randomUUID().toString();

// 原子加锁：SET key value NX PX 毫秒
String result = jedis.set(lockKey, uniqueValue, SetParams.setParams().nx().px(30000));
if ("OK".equals(result)) {
    // 加锁成功
}

到这一步，加锁的原子性问题解决了。但解锁呢？

版本 2.1：安全解锁（Lua 脚本保证原子性）​

很多人解锁时直接 DEL lock_key，这会造成一个严重问题——误删别人的锁。来看一个时间线：

时间轴：

  0s     A 加锁成功（过期时间 30s）
  |      A 开始执行业务...
  |
 30s     锁自动过期！A 的锁没了
 31s     B 加锁成功
  |      B 开始执行业务...
  |
 40s     A 业务终于跑完了，执行 DEL lock_key
         A 把 B 的锁删了！
 41s     C 加锁成功......
         此时 B 和 C 同时在执行，互斥性被打破

解决方案：Value 设成 UUID，删除前先比对是不是自己的锁，是才删除。但关键是：判断 + 删除必须是原子操作，否则在判断之后、删除之前锁过期了仍然会出问题。

所以必须用 Lua 脚本来保证原子性：

-- 解锁 Lua 脚本
if redis.call('get', KEYS[1]) == ARGV[1] then
    return redis.call('del', KEYS[1])
else
    return 0
end

Redis 执行 Lua 脚本是原子的（单线程模型），中间不会被其他命令打断。

// Java 调用 Lua 脚本解锁
String luaScript = 
    "if redis.call('get', KEYS[1]) == ARGV[1] then " +
    "  return redis.call('del', KEYS[1]) " +
    "else " +
    "  return 0 " +
    "end";

Object result = jedis.eval(luaScript, 
    List.of(lockKey),    // KEYS[1]
    List.of(uniqueValue) // ARGV[1]
);

还有什么问题？​

到版本 2.1，我们已经解决了原子加锁和安全解锁两个问题。但还有几个靠手动编码很难完美解决的痛点：

1. 锁过期时间不好设

这是一个两难困境：

• 设短了：业务没执行完锁就过期了，互斥性被打破。
• 设长了：万一节点宕机，其他节点需要等待整个过期周期才能拿到锁，影响可用性。
• 本质问题：业务执行时间难以精确预估。网络抖动、Full GC 停顿、数据量突增，都可能导致实际执行时间远超预期。

2. 不支持可重入

如果同一个线程在持有锁的情况下需要再次加锁（比如嵌套调用），用 SET NX 会失败，因为 Key 已经存在了。

3. 加锁失败没有等待机制

SET NX 失败就直接返回了，想要阻塞等待只能自己写 while 循环轮询，既浪费 CPU 又不优雅。

3. Redisson：工业级解决方案​

Redisson 是一个在 Redis 基础上实现的 Java 驻内存数据网格（In-Memory Data Grid）。它提供的 RLock 几乎完美解决了我们手动实现时遇到的所有痛点：原子性、可重入、自动续期、阻塞等待。

3.1 基本用法​

RLock lock = redisson.getLock("lock:order:12345");
try {
    // 加锁（不指定 leaseTime，自动启用看门狗续期）
    lock.lock();
    // 执行业务逻辑...
} finally {
    // 必须在 finally 中解锁
    if (lock.isHeldByCurrentThread()) {
        lock.unlock();
    }
}

还有一个更常用的 tryLock，支持设置等待时间和锁持有时间：

RLock lock = redisson.getLock("lock:order:12345");
try {
    // 最多等待 5 秒获取锁，获取成功后 30 秒自动释放
    // 注意：指定了 leaseTime 后，看门狗不会启动！
    boolean acquired = lock.tryLock(5, 30, TimeUnit.SECONDS);
    if (acquired) {
        // 执行业务逻辑...
    } else {
        // 5秒内没拿到锁，走降级或提示
    }
} finally {
    if (lock.isHeldByCurrentThread()) {
        lock.unlock();
    }
}

3.2 核心原理揭秘​

Redisson 的强大在于两个核心设计：Lua 脚本保证原子性 + Watchdog（看门狗）自动续期。

(1) 加锁机制​

Redisson 加锁时执行的 Lua 脚本（简化版）：

-- KEYS[1] = 锁的名称
-- ARGV[1] = 过期时间（默认 30000 ms）
-- ARGV[2] = 客户端唯一标识（UUID:threadId）

-- 1. 锁不存在 -> 直接加锁
if (redis.call('exists', KEYS[1]) == 0) then
    redis.call('hincrby', KEYS[1], ARGV[2], 1)    -- 设置持有者，重入次数=1
    redis.call('pexpire', KEYS[1], ARGV[1])        -- 设置过期时间
    return nil                                      -- 返回nil表示加锁成功
end

-- 2. 锁存在，且是自己持有 -> 重入
if (redis.call('hexists', KEYS[1], ARGV[2]) == 1) then
    redis.call('hincrby', KEYS[1], ARGV[2], 1)    -- 重入次数 +1
    redis.call('pexpire', KEYS[1], ARGV[1])        -- 重置过期时间
    return nil
end

-- 3. 锁被别人持有 -> 返回锁的剩余TTL（加锁失败）
return redis.call('pttl', KEYS[1])

注意到没有？Redisson 用的是 Hash 结构（HINCRBY），而不是简单的 String。Key 是锁名，Field 是 UUID:threadId，Value 是重入次数。这就是可重入锁的实现原理——同一个线程再次加锁时，只需要把计数 +1 就行。

在 Redis 中存储的数据长这样：

Key: "lock:order:12345" (Hash类型)
+-----------------------------------+-------+
| Field (UUID:threadId)             | Value |
+-----------------------------------+-------+
| 6f3e8a...:thread-1                |   2   |  <-- 重入了2次
+-----------------------------------+-------+
TTL: 30000ms

(2) Watchdog 看门狗（自动续期）​

这是 Redisson 最精妙的设计，完美解决了「锁过期时间不好设」的难题。

触发条件：只有在不指定 leaseTime 时（即调用 lock() 或 tryLock(waitTime, -1, unit)），看门狗才会启动。

运作机制：

加锁成功
  |
  +-- 默认过期时间 = 30秒（lockWatchdogTimeout）
  |
  +-- 启动后台定时任务，每 10秒（30s / 3）触发一次
  |     |
  |     +-- 检查当前线程是否还持有锁？
  |     |     +-- 是 -> 续期至 30秒，继续定时
  |     |     +-- 否 -> 停止续期
  |     |
  |    ... (每10秒重复)
  |
  +-- [正常情况] 业务跑完 -> 手动 unlock() -> 取消看门狗任务
  |
  +-- [异常情况] 服务宕机 -> 看门狗随进程一起消失
                          -> 没人续期 -> 30秒后锁自动释放

这个设计的巧妙之处：

1. 业务没跑完：看门狗持续续期，锁不会意外过期。
2. 业务跑完了：手动 unlock()，看门狗任务被取消，锁被主动释放。
3. 机器宕机了：看门狗线程也没了，没人续期，30 秒后 Redis 自动删除 Key，锁释放。完美兜底！

(3) 解锁机制​

解锁同样用 Lua 脚本保证原子性（简化版）：

-- KEYS[1] = 锁名称
-- KEYS[2] = 发布/订阅的 channel 名称
-- ARGV[1] = 解锁消息（固定值 0）
-- ARGV[2] = 过期时间
-- ARGV[3] = 客户端标识（UUID:threadId）

-- 1. 锁不是自己的 -> 返回nil（防止误删）
if (redis.call('hexists', KEYS[1], ARGV[3]) == 0) then
    return nil
end

-- 2. 重入次数 -1
local counter = redis.call('hincrby', KEYS[1], ARGV[3], -1)

-- 3. 还有重入层数 -> 不能真正释放，只重置过期时间
if (counter > 0) then
    redis.call('pexpire', KEYS[1], ARGV[2])
    return 0
end

-- 4. 重入次数归零 -> 真正释放锁，并发布通知
redis.call('del', KEYS[1])
redis.call('publish', KEYS[2], ARGV[1])  -- 通知等待的客户端
return 1

注意最后一步的 PUBLISH——Redisson 用 Redis 的**发布/订阅（Pub/Sub）**机制来通知其他等待锁的客户端。当锁被释放时，等待方会收到消息并尝试重新加锁，比傻轮询高效得多。

(4) 等待锁的过程​

当 tryLock 加锁失败时，Redisson 并不是简单地 while(true) 轮询，而是：

1. 订阅锁释放的 Channel（redisson_lock__channel:{锁名}）。
2. 进入阻塞等待（基于 Semaphore），不消耗 CPU。
3. 收到锁释放的通知后，再次尝试加锁。
4. 如果超过 waitTime 仍未获取到，返回 false。

这种「订阅 + 信号量」的方式，比自旋轮询高效很多，大幅减少了无效的 Redis 请求。

3.3 Redisson 的注意事项​

虽然 Redisson 已经足够强大，但仍有几个需要注意的地方：

① 主从切换导致锁丢失​

Redis 主从复制是异步的。考虑这个场景：

1. Client A 在 Master 上加锁成功
2. Master 还没把锁数据同步到 Slave
3. Master 宕机！
4. Slave 升级为 New Master（哨兵/集群自动故障转移）
5. Client B 在 New Master 上加锁成功
   -> 两个客户端同时持有锁！互斥性被打破

解决方案：Redisson 提供了 RedLock 算法（getMultiLock()），向多个独立的 Redis 实例同时请求锁，过半成功才算加锁成功。但实际生产中，RedLock 运维成本较高，且存在争议（Martin Kleppmann 与 Redis 作者 Antirez 的经典论战，感兴趣可搜索 "How to do distributed locking"）。大多数团队选择接受极小概率的锁丢失，或转向 Zookeeper 等 CP 模型的协调服务。

② unlock() 必须加保护​

如果当前线程没有持有锁就调用 unlock()，Redisson 会抛出 IllegalMonitorStateException。所以务必在 finally 中加上判断：

finally {
    // 只有当前线程持有锁时才解锁
    if (lock.isHeldByCurrentThread()) {
        lock.unlock();
    }
}

③ 不要在锁内做耗时 IO​

即使有看门狗续期，也不要在持锁期间做 RPC 调用、大文件读写等耗时操作。持锁时间越长，系统的并发吞吐量越低。原则是快进快出。

4. Zookeeper 分布式锁​

Zookeeper (ZK) 是 CP 模型（强一致性），天然适合做分布式协调。

• 原理：利用 ZK 的临时顺序节点。
  1. 客户端在 /locks 下创建一个临时顺序节点。
  2. 判断自己是不是序号最小的节点？
     • 是 -> 获得锁。
     • 否 -> 监听（Watch）前一个节点。
  3. 前一个节点删除（锁释放或对方挂了），触发 Watch 事件，自己再次判断是否是最小。

对比 Redis vs Zookeeper：

5. 总结​

在大多数互联网业务场景下，Redis (Redisson) 是性价比最高的选择。

• 如果是高并发的互联网业务（秒杀、库存扣减），追求极致性能，能接受极端情况下（主从切换）极小概率的并发冲突 → 选 Redis (Redisson)。
• 如果是金融级场景，涉及资金操作，绝不允许任何并发差错 → 选 Zookeeper 或 数据库悲观锁（适用于并发量不大的场景）。

最后建议：不要自己造轮子去写 Redis 分布式锁（SETNX），坑太多了。直接用 Redisson，省心省力！

本文以 GitHub OAuth 为例，从原理到实践，全面讲解如何在 Spring Boot 项目中实现安全的第三方登录功能。

目录​

• 一、OAuth 2.0 协议深度解析
• 二、安全威胁与防护策略
• 三、注册 GitHub OAuth 应用
• 四、项目架构设计
• 五、核心代码实现
• 六、安全增强实现
• 七、数据库设计
• 八、前端对接
• 九、生产环境部署
• 十、常见问题与排查
• 十一、扩展阅读

一、OAuth 2.0 协议深度解析​

1.1 什么是 OAuth 2.0？​

OAuth 2.0 是一个授权框架（Authorization Framework），它允许第三方应用在用户授权的情况下，访问用户在某个服务上的特定资源，而无需获取用户的密码。

🔑 核心思想：OAuth 解决的是"授权"问题，而非"认证"问题。它让用户可以授权第三方应用访问自己的数据，同时保持密码的私密性。

1.2 OAuth 2.0 四种授权模式​

OAuth 2.0 定义了四种授权模式，适用于不同场景：

本文采用授权码模式（Authorization Code），这是目前最安全、最常用的模式。

1.3 授权码模式完整流程​

1.4 关键参数详解​

授权请求参数​

令牌请求参数​

令牌响应​

二、安全威胁与防护策略​

OAuth 2.0 虽然设计精良，但实现不当仍会引入安全漏洞。以下是常见威胁及防护方案。

2.1 CSRF 攻击（跨站请求伪造）​

什么是 CSRF？​

CSRF（Cross-Site Request Forgery）攻击是指攻击者诱导用户在已登录的状态下，点击恶意链接，从而在用户不知情的情况下完成某些操作。

OAuth 中的 CSRF 攻击场景​

1. 攻击者用自己的 GitHub 账号发起授权，获得授权码 code=abc123
2. 攻击者构造恶意链接：http://你的网站/callback?code=abc123
3. 攻击者诱导受害者点击该链接
4. 受害者的账号被绑定到攻击者的 GitHub 账号！
5. 攻击者可以用自己的 GitHub 登录受害者的账号

这就是著名的 "账号劫持" 攻击。

CSRF 防护方案对比​

本项目的 CSRF 防护方案​

我们采用 State 参数 + Redis 存储 的方案：

1. 用户点击登录，后端生成随机 state 并存入 Redis（TTL 5分钟）
2. 将 state 拼接到授权 URL 中
3. GitHub 回调时携带原样的 state
4. 后端从 Redis 获取并验证 state，验证后立即删除（一次性使用）
5. 验证失败则拒绝登录

优势：

• ✅ 完全符合 OAuth 2.0 规范
• ✅ State 存储在 Redis，支持分布式部署
• ✅ 一次性使用，防止重放攻击
• ✅ 设置 TTL，自动过期清理

2.2 授权码注入攻击​

攻击场景​

攻击者获取到某个用户的授权码后，尝试在自己的会话中使用该授权码。

防护方案​

1. 验证 redirect_uri：换取 token 时校验 redirect_uri 与授权请求一致
2. 授权码绑定会话：将授权码与发起请求的 session 绑定
3. 授权码一次性使用：使用后立即失效

本项目通过 State 参数同时实现了会话绑定和一次性使用。

2.3 Token 泄露风险​

威胁来源​

• 数据库泄露
• 日志泄露
• 网络传输被截获

本项目的防护措施​

2.4 重定向 URI 劫持​

攻击场景​

如果应用没有严格验证 redirect_uri，攻击者可以将用户重定向到恶意网站，窃取授权码。

防护建议​

1. 严格匹配：redirect_uri 必须完全匹配，不使用通配符
2. 白名单验证：维护允许的 redirect_uri 列表
3. HTTPS 强制：生产环境 redirect_uri 必须使用 HTTPS

三、注册 GitHub OAuth 应用​

3.1 创建应用​

1. 登录 GitHub，进入 Settings → Developer settings → OAuth Apps
2. 点击 New OAuth App
3. 填写应用信息：

4. 点击 Register application

3.2 获取凭证​

创建成功后，你会看到：

• Client ID：公开的应用标识，可以放在前端代码中
• Client Secret：必须保密，只能存放在后端

⚠️ 安全提示：切勿将 Client Secret 提交到 Git 仓库，应使用环境变量管理

3.3 多环境配置​

建议为不同环境创建独立的 OAuth App：

# application-dev.yaml（开发环境）
oauth:
  github:
    client-id: ${GITHUB_CLIENT_ID_DEV}
    client-secret: ${GITHUB_CLIENT_SECRET_DEV}

# application-prod.yaml（生产环境）
oauth:
  github:
    client-id: ${GITHUB_CLIENT_ID_PROD}
    client-secret: ${GITHUB_CLIENT_SECRET_PROD}

四、项目架构设计​

4.1 整体架构​

4.2 设计模式应用​

策略模式（Strategy Pattern）​

问题：不同第三方平台（GitHub、Google、微信）的授权流程相似，但具体实现不同。

解决方案：定义统一的策略接口，每个平台实现自己的策略类。

/**
 * OAuth 策略接口
 * 定义所有第三方平台必须实现的方法
 */
public interface OAuthStrategy {
    
    /**
     * 获取平台标识（如 github、google）
     */
    String getProvider();
    
    /**
     * 构建授权 URL
     * @param state CSRF 防护参数
     */
    String getAuthorizeUrl(String state);
    
    /**
     * 用授权码换取用户信息
     * @param code 一次性授权码
     */
    OAuthUserInfo getUserInfo(String code);
    
    /**
     * 创建新用户并绑定第三方账号
     */
    Long createUserOAuth(OAuthUserInfo userInfo);
}

优势：

• ✅ 新增平台只需添加新的策略类，无需修改现有代码
• ✅ 符合开闭原则（对扩展开放，对修改关闭）
• ✅ 便于单元测试

工厂模式（Factory Pattern）​

问题：需要根据平台名称动态获取对应的策略实现。

解决方案：使用策略工厂统一管理所有策略实例。

@Component
public class OAuthStrategyFactory {
    
    private final Map<String, OAuthStrategy> strategyMap;
    
    /**
     * Spring 自动注入所有 OAuthStrategy 实现类
     */
    @Autowired
    public OAuthStrategyFactory(List<OAuthStrategy> strategies) {
        this.strategyMap = strategies.stream()
                .collect(Collectors.toMap(
                        s -> s.getProvider().toLowerCase(),
                        Function.identity()
                ));
    }
    
    public OAuthStrategy getStrategy(String provider) {
        OAuthStrategy strategy = strategyMap.get(provider.toLowerCase());
        if (strategy == null) {
            throw new IllegalArgumentException("不支持的OAuth平台: " + provider);
        }
        return strategy;
    }
}

优势：

• ✅ 利用 Spring 依赖注入自动发现策略类
• ✅ 统一的获取入口，便于管理
• ✅ 支持运行时动态切换策略

五、核心代码实现​

5.1 配置文件​

# application.yaml
server:
  port: 8001
  servlet:
    context-path: /api/user

spring:
  data:
    redis:
      host: localhost
      port: 6379

# OAuth 配置
oauth:
  # 安全配置
  security:
    # AES 加密密钥（32字节），生产环境必须通过环境变量设置
    encryption-key: ${OAUTH_ENCRYPTION_KEY:default32ByteSecretKeyForDev123}
    # State 过期时间（秒）
    state-ttl: 300
  
  # GitHub 配置
  github:
    client-id: ${GITHUB_CLIENT_ID:your-client-id}
    client-secret: ${GITHUB_CLIENT_SECRET:your-client-secret}
  
  # Google 配置（可选）
  google:
    client-id: ${GOOGLE_CLIENT_ID:}
    client-secret: ${GOOGLE_CLIENT_SECRET:}

5.2 数据模型​

OAuth 用户信息（中间对象）​

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OAuthUserInfo {
    
    /** 第三方平台用户ID */
    private String providerUserId;
    
    /** 第三方平台用户名 */
    private String providerUsername;
    
    /** 邮箱 */
    private String email;
    
    /** 头像URL */
    private String avatarUrl;
    
    /** 访问令牌（临时持有，存储前需加密） */
    private String accessToken;
}

State 载荷​

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OAuthStatePayload {
    
    /** 操作类型：LOGIN（登录）或 BIND（绑定） */
    private OAuthStateType type;
    
    /** 用户ID（绑定场景使用） */
    private Long userId;
    
    /** OAuth 平台 */
    private String provider;
    
    /** 创建时间戳 */
    private Long timestamp;
}

5.3 GitHub 策略实现​

@Slf4j
@Component
@RequiredArgsConstructor
public class GitHubOAuthStrategy implements OAuthStrategy {

    private final UserMapper userMapper;
    private final UserOAuthMapper userOAuthMapper;
    private final TokenEncryptionUtil tokenEncryptionUtil;

    @Value("${oauth.github.client-id}")
    private String clientId;
    
    @Value("${oauth.github.client-secret}")
    private String clientSecret;

    // GitHub OAuth 端点
    private static final String AUTHORIZE_URL = "https://github.com/login/oauth/authorize";
    private static final String ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
    private static final String USER_INFO_URL = "https://api.github.com/user";
    private static final String REDIRECT_URI = "http://localhost:8001/api/user/oauth/callback/github";

    @Override
    public String getProvider() {
        return "github";
    }

    @Override
    public String getAuthorizeUrl(String state) {
        // 构建授权 URL，包含 state 参数防止 CSRF
        return String.format(
                "%s?client_id=%s&redirect_uri=%s&scope=user:email&state=%s",
                AUTHORIZE_URL, clientId, REDIRECT_URI, state
        );
    }

    @Override
    public OAuthUserInfo getUserInfo(String code) {
        // 第一步：用授权码换取 access_token
        String accessToken = exchangeCodeForToken(code);
        
        // 第二步：用 access_token 获取用户信息
        return fetchUserInfo(accessToken);
    }
    
    /**
     * 用授权码换取 access_token
     */
    private String exchangeCodeForToken(String code) {
        Map<String, Object> params = new HashMap<>();
        params.put("client_id", clientId);
        params.put("client_secret", clientSecret);
        params.put("code", code);

        String response = HttpUtil.post(ACCESS_TOKEN_URL, params);
        log.debug("GitHub token 请求完成");  // 不要打印响应内容！

        return parseAccessToken(response);
    }
    
    /**
     * 解析 access_token
     * GitHub 可能返回两种格式：URL 编码 或 JSON
     */
    private String parseAccessToken(String response) {
        // 尝试 JSON 格式
        try {
            JSONObject json = JSON.parseObject(response);
            if (json.containsKey("access_token")) {
                return json.getString("access_token");
            }
            if (json.containsKey("error")) {
                throw new RuntimeException("GitHub 授权失败: " + json.getString("error_description"));
            }
        } catch (JSONException ignored) {}

        // URL 编码格式: access_token=xxx&token_type=bearer&scope=user:email
        for (String param : response.split("&")) {
            String[] pair = param.split("=", 2);
            if (pair.length == 2 && "access_token".equals(pair[0])) {
                return pair[1];
            }
        }
        
        throw new RuntimeException("无法解析 GitHub access_token");
    }
    
    /**
     * 获取 GitHub 用户信息
     */
    private OAuthUserInfo fetchUserInfo(String accessToken) {
        try (HttpResponse response = HttpRequest.get(USER_INFO_URL)
                .header("Authorization", "token " + accessToken)
                .header("Accept", "application/json")
                .execute()) {
            
            JSONObject user = JSON.parseObject(response.body());
            
            return OAuthUserInfo.builder()
                    .providerUserId(user.getString("id"))
                    .providerUsername(user.getString("login"))
                    .email(user.getString("email"))
                    .avatarUrl(user.getString("avatar_url"))
                    .accessToken(accessToken)
                    .build();
        }
    }

    @Override
    @Transactional
    public Long createUserOAuth(OAuthUserInfo info) {
        // 1. 创建用户记录
        User user = User.builder()
                .username(info.getProviderUsername())
                .email(info.getEmail())
                .nickname(info.getProviderUsername())
                .avatar(info.getAvatarUrl())
                .build();
        userMapper.insert(user);
        log.info("创建新用户: {}", user.getUsername());

        // 2. 加密 token 并创建绑定关系
        String encryptedToken = tokenEncryptionUtil.encrypt(info.getAccessToken());
        
        UserOAuth binding = UserOAuth.builder()
                .userId(user.getId())
                .provider("github")
                .providerUserId(info.getProviderUserId())
                .providerUsername(info.getProviderUsername())
                .accessToken(encryptedToken)
                .avatarUrl(info.getAvatarUrl())
                .email(info.getEmail())
                .build();
        userOAuthMapper.insert(binding);
        
        log.info("用户 {} 绑定 GitHub 成功", user.getUsername());
        return user.getId();
    }
}

5.4 Service 层​

@Slf4j
@Service
@RequiredArgsConstructor
public class OAuthServiceImpl implements OAuthService {

    private final OAuthStrategyFactory strategyFactory;
    private final OAuthStateService stateService;
    private final TokenEncryptionUtil tokenEncryptionUtil;
    private final UserOAuthMapper userOAuthMapper;

    @Override
    public String getAuthorizeUrl(String provider) {
        // 1. 生成 state 并存入 Redis
        String state = stateService.generateLoginState(provider);
        
        // 2. 获取策略并构建授权 URL
        OAuthStrategy strategy = strategyFactory.getStrategy(provider);
        return strategy.getAuthorizeUrl(state);
    }

    @Override
    @Transactional
    public String handleCallback(String provider, String code, String state) {
        // 1. 验证 state（CSRF 防护）
        OAuthStatePayload payload = stateService.validateAndConsumeState(state);
        if (payload == null) {
            throw new ClientException("授权已过期，请重新登录");
        }
        
        // 2. 验证 state 类型和平台
        if (payload.getType() != OAuthStateType.LOGIN) {
            throw new ClientException("无效的授权类型");
        }
        if (!provider.equalsIgnoreCase(payload.getProvider())) {
            throw new ClientException("授权来源不匹配");
        }

        // 3. 获取第三方用户信息
        OAuthStrategy strategy = strategyFactory.getStrategy(provider);
        OAuthUserInfo userInfo = strategy.getUserInfo(code);

        // 4. 查询是否已绑定
        UserOAuth existing = userOAuthMapper.selectOne(
                Wrappers.<UserOAuth>lambdaQuery()
                        .eq(UserOAuth::getProvider, provider.toLowerCase())
                        .eq(UserOAuth::getProviderUserId, userInfo.getProviderUserId())
        );
        
        Long userId;
        if (existing == null) {
            // 新用户：创建账号并绑定
            userId = strategy.createUserOAuth(userInfo);
        } else {
            // 老用户：直接获取用户ID
            userId = existing.getUserId();
        }

        // 5. 登录并返回 token
        StpUtil.login(userId);
        return StpUtil.getTokenValue();
    }
    
    @Override
    public String getBindAuthorizeUrl(String provider, Long userId) {
        // 绑定场景：state 中包含用户ID
        String state = stateService.generateBindState(provider, userId);
        OAuthStrategy strategy = strategyFactory.getStrategy(provider);
        return strategy.getAuthorizeUrl(state);
    }
    
    @Override
    @Transactional
    public void handleBindCallback(String provider, String code, String state) {
        // 1. 验证 state 并提取用户ID
        OAuthStatePayload payload = stateService.validateAndConsumeState(state);
        if (payload == null || payload.getType() != OAuthStateType.BIND) {
            throw new ClientException("授权已过期，请重新绑定");
        }
        
        Long userId = payload.getUserId();
        
        // 2. 获取第三方用户信息
        OAuthStrategy strategy = strategyFactory.getStrategy(provider);
        OAuthUserInfo userInfo = strategy.getUserInfo(code);
        
        // 3. 检查是否已被其他用户绑定
        UserOAuth existing = userOAuthMapper.selectOne(
                Wrappers.<UserOAuth>lambdaQuery()
                        .eq(UserOAuth::getProvider, provider.toLowerCase())
                        .eq(UserOAuth::getProviderUserId, userInfo.getProviderUserId())
        );
        
        if (existing != null) {
            if (existing.getUserId().equals(userId)) {
                throw new ClientException("您已绑定该账号");
            } else {
                throw new ClientException("该账号已被其他用户绑定");
            }
        }
        
        // 4. 创建绑定关系
        String encryptedToken = tokenEncryptionUtil.encrypt(userInfo.getAccessToken());
        UserOAuth binding = UserOAuth.builder()
                .userId(userId)
                .provider(provider.toLowerCase())
                .providerUserId(userInfo.getProviderUserId())
                .providerUsername(userInfo.getProviderUsername())
                .accessToken(encryptedToken)
                .avatarUrl(userInfo.getAvatarUrl())
                .email(userInfo.getEmail())
                .build();
        userOAuthMapper.insert(binding);
        
        log.info("用户 {} 绑定 {} 成功", userId, provider);
    }
}

5.5 Controller 层​

@Slf4j
@RestController
@RequestMapping("/oauth")
@RequiredArgsConstructor
public class OAuthController {

    private final OAuthService oauthService;

    /**
     * 发起 OAuth 授权
     * GET /oauth/authorize/{provider}
     */
    @GetMapping("/authorize/{provider}")
    public void authorize(@PathVariable String provider, 
                          HttpServletResponse response) throws IOException {
        String authorizeUrl = oauthService.getAuthorizeUrl(provider);
        response.sendRedirect(authorizeUrl);
    }

    /**
     * OAuth 回调处理
     * GET /oauth/callback/{provider}?code=xxx&state=xxx
     */
    @GetMapping("/callback/{provider}")
    public void callback(@PathVariable String provider,
                         @RequestParam("code") String code,
                         @RequestParam(value = "state", required = false) String state,
                         HttpServletResponse response) throws IOException {
        log.info("OAuth 回调: provider={}", provider);
        
        try {
            String token = oauthService.handleCallback(provider, code, state);
            
            // 重定向到前端，携带登录 token
            response.sendRedirect("http://localhost:5173/oauth/callback?token=" + token);
            
        } catch (Exception e) {
            log.error("OAuth 登录失败: {}", e.getMessage());
            response.sendRedirect("http://localhost:5173/login?error=" + 
                    URLEncoder.encode(e.getMessage(), StandardCharsets.UTF_8));
        }
    }

    /**
     * 绑定第三方账号（需登录）
     */
    @GetMapping("/bind/{provider}")
    public void bind(@PathVariable String provider, 
                     HttpServletResponse response) throws IOException {
        Long userId = StpUtil.getLoginIdAsLong();
        String authorizeUrl = oauthService.getBindAuthorizeUrl(provider, userId);
        response.sendRedirect(authorizeUrl);
    }

    /**
     * 绑定回调处理
     */
    @GetMapping("/bind/callback/{provider}")
    public void bindCallback(@PathVariable String provider,
                             @RequestParam("code") String code,
                             @RequestParam("state") String state,
                             HttpServletResponse response) throws IOException {
        try {
            oauthService.handleBindCallback(provider, code, state);
            response.sendRedirect("http://localhost:5173/settings?bind=success");
        } catch (Exception e) {
            log.error("绑定失败: {}", e.getMessage());
            response.sendRedirect("http://localhost:5173/settings?bind=error&message=" + 
                    URLEncoder.encode(e.getMessage(), StandardCharsets.UTF_8));
        }
    }
}

六、安全增强实现​

6.1 State 管理服务​

@Slf4j
@Service
@RequiredArgsConstructor
public class OAuthStateServiceImpl implements OAuthStateService {
    
    private static final String STATE_KEY_PREFIX = "oauth:state:";
    
    private final StringRedisTemplate redisTemplate;
    
    @Value("${oauth.security.state-ttl:300}")
    private long stateTtl;

    @Override
    public String generateLoginState(String provider) {
        return generateState(OAuthStateType.LOGIN, provider, null);
    }
    
    @Override
    public String generateBindState(String provider, Long userId) {
        if (userId == null) {
            throw new IllegalArgumentException("绑定场景必须提供用户ID");
        }
        return generateState(OAuthStateType.BIND, provider, userId);
    }

    @Override
    public OAuthStatePayload validateAndConsumeState(String state) {
        if (state == null || state.isBlank()) {
            log.warn("State 参数为空");
            return null;
        }
        
        String key = STATE_KEY_PREFIX + state;
        
        // 获取并删除（原子操作，确保一次性使用）
        String json = redisTemplate.opsForValue().getAndDelete(key);
        
        if (json == null) {
            log.warn("State 无效或已过期: {}", state);
            return null;
        }
        
        try {
            OAuthStatePayload payload = JSON.parseObject(json, OAuthStatePayload.class);
            log.info("State 验证成功: type={}, provider={}", 
                    payload.getType(), payload.getProvider());
            return payload;
        } catch (Exception e) {
            log.error("State 解析失败", e);
            return null;
        }
    }
    
    private String generateState(OAuthStateType type, String provider, Long userId) {
        // 生成 32 位随机字符串
        String state = UUID.randomUUID().toString().replace("-", "");
        
        OAuthStatePayload payload = OAuthStatePayload.builder()
                .type(type)
                .provider(provider)
                .userId(userId)
                .timestamp(System.currentTimeMillis())
                .build();
        
        String key = STATE_KEY_PREFIX + state;
        String json = JSON.toJSONString(payload);
        
        redisTemplate.opsForValue().set(key, json, stateTtl, TimeUnit.SECONDS);
        
        log.info("生成 State: type={}, provider={}, ttl={}s", type, provider, stateTtl);
        return state;
    }
}