docs: 更新12306专栏内容和新增md文件

Author: LIANGLINJIANG888

docs/.vuepress/config.js

@@ -373,41 +373,27 @@ module.exports = {
                     },
                     {
                         text: '12306',
-                        items: [{
+                        items: [
+                            {
                                 text: '项目介绍',
                                 link: '/md/12306/项目介绍.md'
                             },
                             {
                                 text: '快速开始',
-                                items: [{
+                                items: [
+                                    {
                                         text: '环境搭建',
                                         link: '/md/12306/环境搭建.md'
                                     }
-
                                 ]
                             },
                             {
                                 text: '核心技术文档',
-                                items: [{
+                                items: [
+                                    {
                                         text: '如何生成分布式ID',
                                         link: '/md/12306/如何生成分布式ID.md'
                                     },
-                                    {
-                                        text: '详解雪花算法',
-                                        link: '/md/12306/详解雪花算法.md'
-                                    },
-                                    {
-                                        text: '责任链模式重构复杂业务场景',
-                                        link: '/md/12306/责任链模式重构复杂业务场景.md'
-                                    },
-                                    {
-                                        text: '死磕设计模式之抽象责任链模式',
-                                        link: '/md/12306/死磕设计模式之抽象责任链模式.md'
-                                    },
-                                    {
-                                        text: '策略模式在项目设计中的应用',
-                                        link: '/md/12306/策略模式在项目设计中的应用.md'
-                                    },
                                 ]
                             }
                         ]
@@ -732,7 +718,8 @@ module.exports = {
                             "04-Redisson读写锁加锁机制分析.md"
                         ]
                     }],
-                    "/md/12306/": [{
+                    "/md/12306/": [
+                        {
                             title: "项目介绍",
                             collapsable: false,
                             sidebarDepth: 0,
@@ -758,6 +745,8 @@ module.exports = {
                                 "责任链模式重构复杂业务场景.md",
                                 "死磕设计模式之抽象责任链模式.md",
                                 "策略模式在项目设计中的应用.md",
+                                "死磕设计模式之抽象策略模式.md",
+
                             ]
                         }
                     ],

docs/md/12306/如何生成分布式ID.md

@@ -1,4 +1,4 @@
-# **分布式ID选型**
+# **如何生成分布式ID**
 随着12306开源项目的不断发展，后端服务需要处理来自全国乃至全球的海量请求。在这样的分布式系统中，生成全局唯一且高效的ID是保障数据一致性和服务可靠性的关键。以下是针对12306开源项目的分布式ID选型分析与实践。
 
 ## **项目需求分析**

docs/md/12306/死磕设计模式之抽象策略模式.md

@@ -0,0 +1 @@
+# **死磕设计模式之抽象策略模式**

docs/md/12306/详解雪花算法.md

@@ -1 +1 @@
-# **详解雪花算法**
+# **详解雪花算法**

docs/md/12306/责任链模式重构复杂业务场景.md

@@ -1,2 +1,264 @@
 # **责任链模式重构复杂业务场景**
 
+## 引言：
+
+在软件设计中，我们经常会遇到复杂的业务场景，这些场景往往涉及多个处理对象和一系列操作。为了提高代码的可维护性和扩展性，我们可以采用设计模式来优化结构。其中，责任链模式（Chain of Responsibility）是一种有效的解决方案，它通过将请求沿着链传递来处理复杂的业务逻辑。
+
+责任链模式定义了一系列处理器对象，每个处理器都有机会处理请求。请求会沿着链传递，直到被某个处理器处理或达到链的末端。这种模式降低了发送者和接收者之间的耦合度，使得新增或修改处理器更加灵活。
+
+想要深入了解责任链设计模式的可直接访问<a href ="#jump">#</a>
+
+## 应用场景：
+
+在12306項目中，列车购买车票需要对前端传过来的购票参数进行一系列的校验，包括必填参数不可为空、参数是否满足要求、验证当前车次票数是否充足、乘客是否已购买当前车次等，如果通过if-else处理，虽然也能实现逻辑，但不利于扩展，如果要新增一个校验规则，就得修改当前代码，这样不符合设计模式的开闭原则。
+因此，为了代码的健壮和扩展性，采用了责任链模式进行代码解耦，减少if-else的模板代码出现，提高代码的阅读性和可扩展性。
+
+校验规则主要有如下：
+- 验证参数必填。
+- 检查参数是否有效。
+- 验证列车站点库存是否充足。
+
+每个环节都可以视为一个处理器，它们按照一定的顺序组成了处理链。
+
+## 责任链模式实现：
+
+首先，定义一个全局抽象的处理器接口：
+
+```java
+public interface AbstractChainHandler<T> extends Ordered {
+    /**
+     * 执行责任链逻辑
+     *
+     * @param requestParam 责任链执行入参
+     */
+    void handler(T requestParam);
+
+    /**
+     * @return 责任链组件标识
+     */
+    String mark();
+}
+```
+
+接着，定义每个处理环节的处理器接口，用于区分不同环节的处理器，如下是列车购买车票的校验过滤器
+
+```java
+/**
+ * 列车购买车票过滤器
+ */
+public interface TrainPurchaseTicketChainFilter<T extends PurchaseTicketReqDTO> extends AbstractChainHandler<PurchaseTicketReqDTO> {
+
+    @Override
+    default String mark() {
+        return TicketChainMarkEnum.TRAIN_PURCHASE_TICKET_FILTER.name();
+    }
+}
+```
+具体的列车购票校验器实现类
+
+```java
+/**
+ * 购票流程过滤器之验证参数必填
+ *
+ */
+@Component
+public class TrainPurchaseTicketParamNotNullChainHandler implements TrainPurchaseTicketChainFilter<PurchaseTicketReqDTO> {
+
+    @Override
+    public void handler(PurchaseTicketReqDTO requestParam) {
+        if (StrUtil.isBlank(requestParam.getTrainId())) {
+            throw new ClientException("列车标识不能为空");
+        }
+        if (StrUtil.isBlank(requestParam.getDeparture())) {
+            throw new ClientException("出发站点不能为空");
+        }
+        if (StrUtil.isBlank(requestParam.getArrival())) {
+            throw new ClientException("到达站点不能为空");
+        }
+        if (CollUtil.isEmpty(requestParam.getPassengers())) {
+            throw new ClientException("乘车人至少选择一位");
+        }
+        for (PurchaseTicketPassengerDetailDTO each : requestParam.getPassengers()) {
+            if (StrUtil.isBlank(each.getPassengerId())) {
+                throw new ClientException("乘车人不能为空");
+            }
+            if (Objects.isNull(each.getSeatType())) {
+                throw new ClientException("座位类型不能为空");
+            }
+        }
+    }
+
+    @Override
+    public int getOrder() {
+        return 0;
+    }
+}
+
+/**
+ * 购票流程过滤器之验证参数是否有效
+ */
+@Component
+@RequiredArgsConstructor
+public class TrainPurchaseTicketParamVerifyChainHandler implements TrainPurchaseTicketChainFilter<PurchaseTicketReqDTO> {
+
+    private final TrainMapper trainMapper;
+    private final TrainStationMapper trainStationMapper;
+    private final DistributedCache distributedCache;
+
+    @Override
+    public void handler(PurchaseTicketReqDTO requestParam) {
+        // 查询会员购票车次是否存在，通过封装后安全的 Get 方法
+        TrainDO trainDO = distributedCache.safeGet(
+                TRAIN_INFO + requestParam.getTrainId(),
+                TrainDO.class,
+                () -> trainMapper.selectById(requestParam.getTrainId()),
+                ADVANCE_TICKET_DAY,
+                TimeUnit.DAYS);
+        if (Objects.isNull(trainDO)) {
+            // 如果按照严谨逻辑，类似异常应该记录当前用户的 userid 并发送到风控中心
+            // 如果一段时间有过几次的异常，直接封号处理。下述异常同理
+            throw new ClientException("请检查车次是否存在");
+        }
+        // TODO，当前列车数据并没有通过定时任务每天生成最新的，所以需要隔离这个拦截。后期定时生成数据后删除该判断
+        if (!EnvironmentUtil.isDevEnvironment()) {
+            // 查询车次是否已经发售
+            if (new Date().before(trainDO.getSaleTime())) {
+                throw new ClientException("列车车次暂未发售");
+            }
+            // 查询车次是否在有效期内
+            if (new Date().after(trainDO.getDepartureTime())) {
+                throw new ClientException("列车车次已出发禁止购票");
+            }
+        }
+        // 车站是否存在车次中，以及车站的顺序是否正确
+        String trainStationStopoverDetailStr = distributedCache.safeGet(
+                TRAIN_STATION_STOPOVER_DETAIL + requestParam.getTrainId(),
+                String.class,
+                () -> {
+                    LambdaQueryWrapper<TrainStationDO> queryWrapper = Wrappers.lambdaQuery(TrainStationDO.class)
+                            .eq(TrainStationDO::getTrainId, requestParam.getTrainId())
+                            .select(TrainStationDO::getDeparture);
+                    List<TrainStationDO> actualTrainStationList = trainStationMapper.selectList(queryWrapper);
+                    return CollUtil.isNotEmpty(actualTrainStationList) ? JSON.toJSONString(actualTrainStationList) : null;
+                },
+                Index12306Constant.ADVANCE_TICKET_DAY,
+                TimeUnit.DAYS
+        );
+        List<TrainStationDO> trainDOList = JSON.parseArray(trainStationStopoverDetailStr, TrainStationDO.class);
+        boolean validateStation = validateStation(
+                trainDOList.stream().map(TrainStationDO::getDeparture).toList(),
+                requestParam.getDeparture(),
+                requestParam.getArrival()
+        );
+        if (!validateStation) {
+            throw new ClientException("列车车站数据错误");
+        }
+    }
+
+    @Override
+    public int getOrder() {
+        return 10;
+    }
+
+    public boolean validateStation(List<String> stationList, String startStation, String endStation) {
+        int index1 = stationList.indexOf(startStation);
+        int index2 = stationList.indexOf(endStation);
+        if (index1 == -1 || index2 == -1) {
+            return false;
+        }
+        return index2 >= index1;
+    }
+}
+
+/**
+ * 购票流程过滤器之验证列车站点库存是否充足
+ */
+@Component
+@RequiredArgsConstructor
+public class TrainPurchaseTicketParamStockChainHandler implements TrainPurchaseTicketChainFilter<PurchaseTicketReqDTO> {
+
+    private final SeatMarginCacheLoader seatMarginCacheLoader;
+    private final DistributedCache distributedCache;
+
+    @Override
+    public void handler(PurchaseTicketReqDTO requestParam) {
+        // 车次站点是否还有余票。如果用户提交多个乘车人非同一座位类型，拆分验证
+        String keySuffix = StrUtil.join("_", requestParam.getTrainId(), requestParam.getDeparture(), requestParam.getArrival());
+        StringRedisTemplate stringRedisTemplate = (StringRedisTemplate) distributedCache.getInstance();
+        List<PurchaseTicketPassengerDetailDTO> passengerDetails = requestParam.getPassengers();
+        Map<Integer, List<PurchaseTicketPassengerDetailDTO>> seatTypeMap = passengerDetails.stream()
+                .collect(Collectors.groupingBy(PurchaseTicketPassengerDetailDTO::getSeatType));
+        seatTypeMap.forEach((seatType, passengerSeatDetails) -> {
+            Object stockObj = stringRedisTemplate.opsForHash().get(TRAIN_STATION_REMAINING_TICKET + keySuffix, String.valueOf(seatType));
+            int stock = Optional.ofNullable(stockObj).map(each -> Integer.parseInt(each.toString())).orElseGet(() -> {
+                Map<String, String> seatMarginMap = seatMarginCacheLoader.load(String.valueOf(requestParam.getTrainId()), String.valueOf(seatType), requestParam.getDeparture(), requestParam.getArrival());
+                return Optional.ofNullable(seatMarginMap.get(String.valueOf(seatType))).map(Integer::parseInt).orElse(0);
+            });
+            if (stock >= passengerSeatDetails.size()) {
+                return;
+            }
+            throw new ClientException("列车站点已无余票");
+        });
+    }
+
+    @Override
+    public int getOrder() {
+        return 20;
+    }
+}
+```
+将上述的列车购票校验处理器组装成一条链：
+
+```java
+/**
+ * 抽象责任链上下文
+ */
+public final class AbstractChainContext<T> implements CommandLineRunner {
+
+    private final Map<String, List<AbstractChainHandler>> abstractChainHandlerContainer = new HashMap<>();
+
+    /**
+     * 责任链组件执行
+     *
+     * @param mark         责任链组件标识
+     * @param requestParam 请求参数
+     */
+    public void handler(String mark, T requestParam) {
+        List<AbstractChainHandler> abstractChainHandlers = abstractChainHandlerContainer.get(mark);
+        if (CollectionUtils.isEmpty(abstractChainHandlers)) {
+            throw new RuntimeException(String.format("[%s] Chain of Responsibility ID is undefined.", mark));
+        }
+        abstractChainHandlers.forEach(each -> each.handler(requestParam));
+    }
+
+    @Override
+    public void run(String... args) throws Exception {
+        Map<String, AbstractChainHandler> chainFilterMap = ApplicationContextHolder
+                .getBeansOfType(AbstractChainHandler.class);
+        chainFilterMap.forEach((beanName, bean) -> {
+            List<AbstractChainHandler> abstractChainHandlers = abstractChainHandlerContainer.get(bean.mark());
+            if (CollectionUtils.isEmpty(abstractChainHandlers)) {
+                abstractChainHandlers = new ArrayList();
+            }
+            abstractChainHandlers.add(bean);
+            List<AbstractChainHandler> actualAbstractChainHandlers = abstractChainHandlers.stream()
+                    .sorted(Comparator.comparing(Ordered::getOrder))
+                    .collect(Collectors.toList());
+            abstractChainHandlerContainer.put(bean.mark(), actualAbstractChainHandlers);
+        });
+    }
+}
+```
+最后，在列车购票服务中使用。
+```java
+   @Override
+   public TicketPurchaseRespDTO purchaseTicketsV1(PurchaseTicketReqDTO requestParam) {
+        // 责任链模式，验证 1：参数必填 2：参数正确性 3：乘客是否已买当前车次等...
+        purchaseTicketAbstractChainContext.handler(TicketChainMarkEnum.TRAIN_PURCHASE_TICKET_FILTER.name(), requestParam);
+        // other logic 省略        
+}
+```
+
+## 总结：
+
+通过使用责任链模式，我们成功地将复杂的列购票处理流程分解成了独立、可管理的处理器链。这种设计提高了代码的模块化程度，降低了各个处理器之间的耦合性，同时也便于后续的功能扩展和维护。