企业官网建设流程全解析

1. 项目概述与整体设计

1.1 为什么我选择 SpringBoot3 做报修平台

做智慧社区报修平台这个项目，其实不是心血来潮。我在小区物业群里看多了业主吐槽"报修两周没人管""报修了也不知道修到哪一步"，传统报修流程全靠微信群接龙和物业内部纸质工单，消息一多就石沉大海。做这个平台的核心诉求就三个：业主能方便提交报修、物业能高效派单、维修工能按优先级处理，同时整个过程要留痕、可追溯。

选技术栈时，我几乎没有犹豫就锁定了 SpringBoot3。原因有三点：一是 SpringBoot3 基于 Spring Framework 6，性能底子比 2.x 扎实，正好社区报修平台这种面向 C 端的小型系统，启动速度和内存占用都很关键；二是 SpringBoot3 强制要求 Jakarta EE 9+ 标准，javax 包全面迁移到 jakarta，这是未来长期维护的方向，我不想再做一个新项目还背老包袱；三是 SpringBoot3 在配置管理、原生镜像支持这些方面做了大量优化，尤其是外部化配置能力，非常适合需要灵活部署的物业侧系统。

这个项目里，外部化配置和 AOP 两个点是我刻意放大的技术线。外部化配置解决的是"不改代码就能改行为"的问题，比如不同小区、不同物业的账单规则、派单策略、催单时间阈值，这些业务规则如果写死在代码里，每换一个小区就得重新发版，开发效率会被拖垮。AOP 解决的是"横切逻辑"的问题，像操作审计、异常通知、耗时监控这些逻辑散布在每个业务方法里，如果到处手写，代码会极其臃肿，用 AOP 统一收敛才是正解。

1.2 报修平台的核心业务链路

在动手写代码之前，我先把业务模型理清。这个平台涉及四类角色：

核心流程是一条状态链路：草稿 -> 待审核 -> 待派单 -> 已接单 -> 维修中 -> 待验收 -> 已完成/已关闭。每一步状态流转都会触发业务动作，比如状态变为"已接单"时要给业主发通知，状态变为"维修中"时要记录开始时间用于计算超时。

我设计表结构时，最重要的三张核心表是repair_order（报修单主表）、repair_order_log（状态流转日志）、repair_config（报修规则配置表）。报修单主表存当前状态、业主 ID、维修工 ID、优先级等关键字段，状态日志表记录每一次流转的操作用户、操作时间、变更前后状态，配置表则将军团催单阈值、自动派单策略、超时时间等做成可热更新的配置项。

这三张表一画出来，整个系统的主干就清楚了。接下来的技术选型都是围绕这条业务链路展开的。

2. 外部化配置：原理与实操

2.1 SpringBoot3 配置加载优先级，必须刻在脑子里

外部化配置这个词，听起来有点官方，本质上就是"把配置从代码里拿出来，放到环境里"。SpringBoot3 的配置源非常多，包括命令行参数、环境变量、application.yml、application-{profile}.yml、随机值、JNDI、Servlet 参数等，它们的优先级从高到低遵循一套严格规则。

我直接说结论：命令行参数 > Java 系统属性 > 操作系统环境变量 > application-{profile}.yml > application.yml > 内置默认配置。这条优先级链是排查配置不生效问题的第一把钥匙。比如你在 application.yml 里配了server.port=8081，命令行启动时又带了--server.port=9090，最终生效的一定是 9090。

为什么需要这样的设计？核心原因在于环境差异。同一套代码，在开发环境连接本地数据库，在测试环境连接测试库，在生产环境连接正式库，如果这些信息写死在代码里，每次部署都要改代码重新打包，这违背了"一次构建，多处运行"的基本原则。把环境相关的内容从代码中剥离出来，配置就能跟随环境走，代码则与运行环境解耦。

SpringBoot3 里配置绑定的核心机制是Environment抽象和Binder。Environment负责统一管理所有配置源，Binder负责把配置值绑定到 Java 对象上。我建议项目中尽量使用@ConfigurationProperties而不是散落各处的@Value，因为前者能把一批相关配置绑定到一个强类型对象上，自带类型校验和默认值处理，后者遇到配置缺失时启动阶段就报错，排查起来费劲。

@Component @ConfigurationProperties(prefix = "repair.order") public class RepairOrderProperties { /** * 自动派单超时时间(分钟) */ private Integer autoDispatchTimeout = 30; /** * 催单时间间隔(分钟) */ private Integer remindInterval = 120; /** * 是否开启超时自动升级 */ private Boolean timeoutAutoEscalate = false; public Integer getAutoDispatchTimeout() { return autoDispatchTimeout; } public void setAutoDispatchTimeout(Integer autoDispatchTimeout) { this.autoDispatchTimeout = autoDispatchTimeout; } // 其它getter/setter省略 }

这里有个 SpringBoot 的"宽松绑定"特性值得多说两句。prefix = "repair.order"对应配置文件里的repair.order.auto-dispatch-timeout，中划线命名和驼峰命名会自动对应，不需要做任何转换。这是 Spring 干活儿时特意留的容错空间，我自己偶尔也会用REPAIR_ORDER_AUTODISPATCHTIMEOUT这种全大写下划线形式，尤其是在环境变量里。不过我提醒你，配置键别来回乱变风格，团队一旦定了一个规则就统一遵守，否则排查问题的时候很容易找不着北。

2.2 使用 profile 做多环境隔离的落地姿势

配置隔离是外部化配置最典型的应用场景。我见过不少项目在一个application.yml文件里塞满所有环境的配置，用注释区分"开发""测试""生产"，这种做法的隐患在于：改配置时容易误动别的环境，发布时还得小心翼翼挑着改，手动操作一多就容易出事故。

SpringBoot 的 profile 机制就是专门解决这个问题的。application-dev.yml放开发环境配置，application-prod.yml放生产环境配置，公共配置留在application.yml。激活方式有三种：启动命令加--spring.profiles.active=prod，环境变量设SPRING_PROFILES_ACTIVE=prod，或者在部署平台的启动脚本里固定写好。Shiro 不在这里，我们继续说 Spring。

我的报修平台里，三套环境的差异集中在数据源、Redis、日志级别、基础 URL 这几个维度。开发环境日志级别是 DEBUG，生产环境是 WARN；开发环境的数据库是本地的，生产环境走的是云上的内网地址。这些差异通过 profile 文件天然隔离，发布时只需要把--spring.profiles.active=prod传进去，其他什么都不用改。

需要注意 profile 专属文件有一个"覆盖"关系：application-prod.yml中的配置会覆盖application.yml中的同名配置，但application.yml中独有的配置不会丢失。这个机制很适合"默认值放公共配置、覆盖项放环境配置"的玩法。

2.3 报修平台的实际配置方案：从配置中心到动态刷新

做了几个项目之后我有个感受：外部化配置的尽头往往是配置中心。社区报修平台如果只部署一套、服务单一，用 yml 文件完全够用；但如果需要管理几十个小区实例，或者运营人员要经常调整催单策略、派单规则，配置文件方式就不够灵活了。

报修平台里，我真正需要动态调整的配置有两类：

一类是业务规则参数，比如"业主催单触发阈值"（超过多少分钟算超时并触发提醒）、"自动派单窗口期"（维修工多少分钟内不接单就自动改派）、"维修工时上限"。这些参数如果写死在 yml 里，每次调整都要重启服务，报修高峰期碰到"这个小区维修工不够，要把超时时间从 30 分钟改成 60 分钟"的需求，重启可不是好选择。

另一类是开关配置，比如"是否开启短信通知""是否允许业主取消报修""是否启用维修评价"。

这类配置我采用了"数据库配置表 + 本地缓存 + 定时刷新"的模式。具体做法是：建一张repair_config表，配置项以 key-value 形式存储，项目启动时把配置加载到本地缓存，再用@Scheduled定时任务每 30 秒刷新一次缓存。这样运营人员在后台管理界面修改配置后，最多半分钟内就能生效，无需重启。

@Component public class RepairConfigHolder { private final RepairConfigMapper configMapper; private final Map<String, String> configCache = new ConcurrentHashMap<>(); public RepairConfigHolder(RepairConfigMapper configMapper) { this.configMapper = configMapper; } /** * 应用启动时加载配置到本地缓存 */ @PostConstruct public void init() { refresh(); } /** * 定时刷新配置 */ @Scheduled(fixedDelay = 30_000) public void refresh() { List<RepairConfig> configs = configMapper.selectAll(); Map<String, String> newCache = new ConcurrentHashMap<>(); for (RepairConfig config : configs) { newCache.put(config.getConfigKey(), config.getConfigValue()); } configCache.clear(); configCache.putAll(newCache); } public String get(String key, String defaultValue) { return configCache.getOrDefault(key, defaultValue); } public Integer getInt(String key, Integer defaultValue) { String value = configCache.get(key); if (value == null) { return defaultValue; } return Integer.parseInt(value); } }

整体方案就成了：外部化配置管"不变的环境差异"，配置中心/配置表管"多变的业务规则"。前者保证部署灵活，后者保证运行时可调，两者配合才能覆盖真实的运维需求。

3. AOP 核心原理：它到底在解决什么问题

3.1 从代理模式说起：Spring AOP 的底层灵魂

很多人学 AOP 容易卡在概念上，搞不清"切面""切点""通知"在说什么。我换个说法：AOP 本质上是代理模式在生产代码中的应用，就是要解决"怎么在不修改原始代码的情况下，给方法加功能"这个问题。

举一个报修平台里的实际例子。提交报修单的方法RepairOrderService.submit()里，除了核心逻辑"存一条报修记录"，还需要辅助逻辑"写操作日志""检查用户是否被限制报修""发送通知"。如果这些逻辑都直接写进submit()方法，这个方法会越来越臃肿，而且"写操作日志"这种逻辑在cancel()、assign()、complete()方法里也要用，代码重复率高到你不想维护。

AOP 的思路是：把"写操作日志"这种横切逻辑提取成一个独立模块（切面），然后在运行时使用代理对象替代原始对象。调用方拿到的是代理对象，调用submit()方法时，代理对象先执行"写操作日志"，再调用原始对象的submit()方法。

Spring AOP 底层有两种代理方式。SpringBoot2.x 时代开始，Spring 默认使用CGLIB 动态代理，生成原始类的子类作为代理对象。这意味着一个 Hard 的事实：使用 Spring AOP 代理的类不能是 final 类，被增强的方法不能是 final 方法。如果类被标记为 final，CGLIB 无法生成子类，代理就会失败；如果方法是 private 的，CGLIB 也无法覆盖它。这一点在越界很容易踩到，后面避坑部分我会重点讲。

3.2 Advice、Pointcut 和 Aspect 之间的关系

AOP 三个核心概念，我用报修流程来对应解释：

• Aspect（切面）：一个模块化的横切关注点集合。比如"维修工接单操作审计切面"，就是一个切面类。
• Pointcut（切点）：定义"在哪些方法上生效"。比如"凡是RepairOrderService中以assign开头的 public 方法"，就是一个切点表达式。
• Advice（通知）：定义"在方法执行的什么时机做什么事"。比如"方法执行成功后记录审计日志"，就是一个 AfterReturning 通知。

Spring AOP 提供了五种通知类型：

掌握这个概念后，写代码实际就是在"选择切点表达式"和"编写通知逻辑"之间填空。切点表达式是指定"哪些方法会被拦截"的规则，比较常用的有几种写法：

@Pointcut("execution(* com.community.repair.service.RepairOrderService.*(..))") public void orderServiceMethods() {}

• execution: 方法级别匹配，最常用，比如上方写法表示"匹配 RepairOrderService 所有方法"。
• within: 按类/包级别匹配，比如within(com.community.repair.service..*)匹配 service 包下所有类的方法。
• @annotation: 按注解匹配，比如想要拦截所有标注了@AuditLog的方法，就写@annotation(com.community.repair.aspect.AuditLog)。
• args: 按参数类型匹配，比如args(RepairOrder)匹配入参包含RepairOrder的方法。

我自己的经验是：能用注解切点的场景优先用注解切点。因为execution表达式挂在包名/类名上，一旦类重构、包路径调整，表达式就失效了，而且代码里看不出这个类的方法被什么切面拦截。而用自定义注解标注在方法上，代码阅读者一眼就能看到这个方法是受 AOP 管理的，维护成本更低。

4. AOP 在报修平台中的三个实际落点

4.1 做法一：用自定义注解实现操作审计日志

报修平台最关键的非功能性需求之一就是"所有关键操作必须留痕"。业主要能查到"我的报修单为什么状态变了"，物业管理员要能追踪"谁在什么时间改了什么"。如果每个业务方法里手动写日志，代码量爆炸，还容易漏写。

我定义了一个@AuditLog注解，标注在需要审计的业务方法上：

@Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface AuditLog { /** * 操作类型描述，如"提交报修""派单""验收报修" */ String action() default ""; /** * 操作对象类型，如"repair_order" */ String targetType() default ""; }

然后在业务方法上直接标注：

@AuditLog(action = "提交报修", targetType = "repair_order") public Long submitRepairOrder(RepairOrderCreateRequest request) { // 核心业务逻辑 } @AuditLog(action = "确认完工", targetType = "repair_order") public void confirmRepair(Long orderId) { // 核心业务逻辑 }

对应的切面类就负责统一处理审计日志的收集和入库：

@Aspect @Component public class AuditLogAspect { private final RepairOrderLogMapper logMapper; public AuditLogAspect(RepairOrderLogMapper logMapper) { this.logMapper = logMapper; } @Around("@annotation(auditLog)") public Object doAudit(ProceedingJoinPoint pjp, AuditLog auditLog) throws Throwable { String methodName = pjp.getSignature().getName(); Object[] args = pjp.getArgs(); Long operatorId = SecurityUtils.getCurrentUserId(); String operatorName = SecurityUtils.getCurrentUserName(); long startTime = System.currentTimeMillis(); try { Object result = pjp.proceed(); long costTime = System.currentTimeMillis() - startTime; // 记录成功日志 saveAuditLog(auditLog.action(), auditLog.targetType(), operatorId, operatorName, JSON.toJSONString(args), "SUCCESS", costTime, null); return result; } catch (Throwable e) { long costTime = System.currentTimeMillis() - startTime; // 记录失败日志，同时包装异常 saveAuditLog(auditLog.action(), auditLog.targetType(), operatorId, operatorName, JSON.toJSONString(args), "FAILED", costTime, e.getMessage()); throw e; } } private void saveAuditLog(String action, String targetType, Long operatorId, String operatorName, String requestData, String resultStatus, long costTime, String errorMsg) { RepairOrderLog log = new RepairOrderLog(); log.setAction(action); log.setTargetType(targetType); log.setOperatorId(operatorId); log.setOperatorName(operatorName); log.setRequestData(requestData); log.setResultStatus(resultStatus); log.setCostTimeMs(costTime); log.setErrorMsg(errorMsg); log.setCreateTime(new Date()); logMapper.insert(log); } }

这里有一个关键细节：@annotation(auditLog)这种切点写法会把AuditLog注解对象作为参数传入通知方法，这样在切面里可以直接拿到注解上的action和targetType，不需要在方法体里重复写死。这个方法比"用反射在 proceed 前从方法上读取注解"要简洁得多，也是 Spring AOP 提供的便利特性。

自己动手做的时候，最容易漏掉的是操作人和操作时间。操作人不能从方法参数里拿，而是从安全上下文中拿（示例里是SecurityUtils.getCurrentUserId()），这也是 AOP 的价值——横切逻辑统一从全局上下文取数据，不需要每个业务方法手动传递。我之前看到过有的团队把操作人放在 request 参数的每个 DTO 里传来传去，代码冗余程度相当高。

4.2 做法二：AOP 统一处理维修工接单超时监控

报修平台有一个业务痛点：工单派给维修工后，如果维修工一直不接单，业主等待时间就会拉长。产品要求实现"派单后 30 分钟未接单，自动提醒；60 分钟未接单，自动改派给其他维修工"。

这个逻辑如果用@Scheduled定时任务全表扫描，实现很直接：每分钟查一次repair_order表，找出status = '待接单'且update_time < now() - 30分钟的记录，批量处理。但当单量大了以后，全表扫描的代价会越来越高，而且"从什么时候开始计算超时"的数据不好维护，因为超时判断需要记录派单时间，如果派单时间更新在状态字段里，每次状态变化都要去更新最后操作时间，容易出错。

我用的方案是 AOP + 内存延迟队列的组合。在派单方法上做一个@Around通知，方法执行成功拿到工单 ID 后，把"工单 ID + 最后接单时间"放进程内延迟队列：

@Aspect @Component public class DispatchTimeoutAspect { private final DispatchTimeoutHandler timeoutHandler; public DispatchTimeoutAspect(DispatchTimeoutHandler timeoutHandler) { this.timeoutHandler = timeoutHandler; } @Around("execution(* com.community.repair.service.DispatchService.dispatch(..))") public Object scheduleTimeoutCheck(ProceedingJoinPoint pjp) throws Throwable { Object result = pjp.proceed(); if (result != null) { Long orderId = (Long) result; // 派单成功后，延迟 30 分钟检查接单状态 timeoutHandler.scheduleCheck(orderId, 30, TimeUnit.MINUTES); } return result; } }

DispatchTimeoutHandler内部用一个ScheduledExecutorService实现了延迟任务：30 分钟后执行"检查订单是否已被接单"，如果仍然处于待接单状态，触发提醒或者自动改派逻辑。这样好处在于：超时任务只在派单成功后创建，不会像定时全表扫描那样带来无效查询；而且任务的触发时机和派单动作精确绑定，调度逻辑清晰。

这里我需要说明一下，为什么"派单超时"这种看起来可以用定时任务解决的场景也适合 AOP。因为把"调度超时检查"这个动作从派单业务方法里抽出来，派单服务只关心"派单"，超时监控由切面在幕后无感执行，业务代码不会出现"又处理业务又写调度代码"的混乱状态。不过，当前这个方案适合单实例部署，如果系统是多实例部署，进程内延迟队列会出现任务只在一个实例上执行、其它实例不感知的问题，需要改为 Redis 延迟队列等分布式方案，这个大家要根据部署规模灵活判断。

4.3 做法三：记录报修单状态流转的关键链路

还有一个非常典型的 AOP 场景，就是用@AfterReturning统一记录状态变更日志。

报修单状态从"待审核"变为"待派单"，从"已接单"变为"维修中"，这些状态变化必然发生在某个业务方法里。我最初的做法是在每个方法里手动插入一条repair_order_log记录，后来发现代码重复严重，而且有的方法改了状态，忘了插日志，审计链就断了。

用 AOP 后，我在RepairOrderService内部定义一个专门用于状态变更的方法：

public void changeOrderStatus(Long orderId, RepairOrderStatus targetStatus, String remark) { RepairOrder order = repairOrderMapper.selectById(orderId); RepairOrderStatus fromStatus = order.getStatus(); // 状态校验：是否允许从 fromStatus 流转到 targetStatus if (!statusFlowValidator.canTransit(fromStatus, targetStatus)) { throw new RepairOrderException(ErrorCode.INVALID_STATUS_TRANSITION); } order.setStatus(targetStatus); repairOrderMapper.updateById(order); // 记录流转日志交给 AOP 处理 statusChangeHolder.setContext(orderId, fromStatus, targetStatus, remark); }

用@Around切面拦截changeOrderStatus方法成功后，从StatusChangeContext（ThreadLocal 中的上下文）取出本次状态变化信息，统一写入repair_order_log表。这样业务方法里没有任何日志代码，日志完整性由切面保证。

用 ThreadLocal 传递上下文信息到切面里，这是我在实际项目里经常用的模式。它解决了"切面拿不到业务方法内部局部数据"的问题，但需要注意ThreadLocal 必须在使用后清理，否则线程池复用线程时会有脏数据。

我用的清理方式是在切面的 finally 块里调用contextHolder.clear()。这一点在异步场景下尤其关键——如果业务方法内有子线程继续使用 ThreadLocal，切面清理时机就要把握好，否则会出现"日志记录成功但上下文已清空"的问题。

5. 避坑指南与排查实录

5.1 配置不生效的三大经典原因

配置文件根本没被加载。SpringBoot3 默认加载 classpath 下的application.yml或application.properties。如果你把配置文件放在了别的位置，或者打成了 jar 包后在外部修改了配置但没放在指定加载路径下，应用启动时不会自动读取。我建议用--spring.config.location参数显式指定外部配置文件的位置，而不是期望 Spring 自动发现。

Profile 没有激活。这是我在测试环境踩过最多次的坑：写了application-prod.yml，但启动命令没带--spring.profiles.active=prod，Spring 默认只加载application.yml，结果 prod 配置全部没生效，数据库连接串还是开发环境的。

用启动脚本固定激活参数是个好习惯：

java -jar repair-platform.jar \ --spring.profiles.active=${SPRING_PROFILE} \ --spring.config.location=file:/opt/repair/config/

配置键名拼写不一致。@ConfigurationProperties(prefix = "repair.order")要求配置文件里写repair.order.auto-dispatch-timeout，如果我写成repair.order.autoDispatchTimeout就不行——严格来说，SpringBoot 的宽松绑定支持驼峰和下划线互转，但不支持完全随意的命名。如果你用的是 IDEA，强烈建议装 Spring Boot 插件，配置文件里会有自动提示和拼写检查，这能省大量排查时间。

5.2 Spring AOP 的切点不生效，九成原因是这几类

我把 AOP 切点不生效的排查路径总结成一张速查表，遇到问题挨个排除就对了：

这里重点讲"同类内部调用"问题。Spring AOP 的代理对象只在外部调用时生效：

@Service public class RepairOrderService { public Long submitRepairOrder(RepairOrderCreateRequest request) { // 非 AOP 生效场景 Long orderId = this.confirmInternal(request); return orderId; } @AuditLog(action = "提交报修", targetType = "repair_order") public Long confirmInternal(RepairOrderCreateRequest request) { return createOrder(request); } }

当你从submitRepairOrder()方法内部调用this.confirmInternal()时，实际调用的不是 Spring 容器里的代理对象，而是原始对象，所以@AuditLog切面不会执行。这是我自己刚开始做 AOP 时踩过的最典型的坑。

解决方式有两种：一是把confirmInternal()拆到另一个独立的 Bean（比如RepairOrderCommandService）中，让RepairOrderService注入它，这样外部调用会经过代理；二是用AopContext.currentProxy()获取代理对象后再调用，但需要显式开启@EnableAspectJAutoProxy(exposeProxy = true)。这种方式有侵入性，我一般更推荐拆分 Bean 的方式，因为职责也更清晰。

5.3 @Transactional 与自定义 AOP 的执行顺序

报修平台里，提交报修涉及"创建订单 + 初始化流程 + 首次通知"，我需要保证这是一个事务。但同时我又想在事务提交成功后再发通知，避免"事务回滚了但通知已经发出去了"这种不一致现象。

这就涉及@Transactional事务切面和自定义 AOP 切面的执行顺序。Spring 中多个切面在同一方法上可以指定优先级，用@Order注解控制。

关键规则：优先级值越小，执行顺序越靠前。默认情况下，@Transactional的优先级是Ordered.LOWEST_PRECEDENCE，也就是说它最晚执行。所以如果你在submitRepairOrder()上同时加了@Transactional和自定义的@AuditLog，执行顺序是：自定义切面在前，事务切面在后。这意味着自定义切面的 @Around 方法里，如果调用pjp.proceed()之后立即执行代码，此时事务可能还没提交。

我为了让"发通知"逻辑等事务提交后再执行，把通知切面的@Order调成比事务切面低（数值更大），同时事务切面保持默认。但实践中更好的方式其实是使用 Spring 的事务同步机制：在事务内注册TransactionSynchronization，在afterCommit时执行通知。这个是 Spring 提供的官方能力，比硬调切面顺序更优雅。

public void submitRepairOrder(RepairOrderCreateRequest request) { // 业务操作 Long orderId = createOrder(request); // 注册事务同步回调 TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { @Override public void afterCommit() { notifyService.sendCreateOrderNotification(orderId); } }); }

写代码的时候我特意把这个点分享出来，是因为"事务提交后发通知"是很多业务系统的通用需求，只用 @Order 调切面优先级容易让后续维护的人一头雾水，而TransactionSynchronization语义上更清晰、灵活度更高。

5.4 SpringBoot3 特有的一些坑

javax 包名报错是最常见的。SpringBoot3 已经全面迁移到 Jakarta 命名空间，网上大量旧教程的import javax.persistence.*、import javax.validation.*在 SpringBoot3 项目里会直接编译失败。解决方式是统一替换为jakarta.persistence.*、jakarta.validation.*。如果是老项目往 SpringBoot3 升级，这一步几乎是必经之路。

第三方库的兼容性也要提前确认。SpringBoot3 要求依赖的框架也基于 Spring Framework 6，很多老版本的 mybatis-spring-boot-starter、pagehelper-spring-boot-starter 并不直接支持 SpringBoot3。我之前选型时翻了好几个 starter 的文档，最终锁定了官方适配版本。我建议你在项目搭建阶段就列一张依赖清单，逐个确认是否支持 Spring Boot 3，避免开发到一半发现某个关键依赖跑不起来。

6. 完整实操：从零搭建报修平台的核心模块

6.1 项目骨架与 Maven 依赖

我们来看一个最小可跑的 SpringBoot3 项目骨架。用 IDEA 的 Spring Initializr 创建项目时，关键结构如下：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.4</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-aop</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.5</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>

这里特别说一下spring-boot-starter-aop。SpringBoot 的 AOP starter 会自动引入spring-aop和aspectjweaver，不需要单独再配一遍。另外 MyBatis-Plus 3.5.5 是我验证过的兼容 SpringBoot3 版本，用低版本可能遇到兼容问题，建议避开。

6.2 配置文件的关键内容

application.yml里放公共配置：

spring: application: name: repair-platform datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: ${DB_USERNAME} password: ${DB_PASSWORD} mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl map-underscore-to-camel-case: true global-config: db-config: id-type: assign_id

注意一个关键细节：数据库连接信息我用${DB_HOST}这种占位符方式，而不是把明文写死。这样配置信息完全由外部环境变量注入，部署到哪套环境都不需要改配置文件。这是遵循"应用中不包含环境相关配置"的原则。

application-prod.yml加生产环境的特有配置：

server: port: 8080 spring: datasource: url: jdbc:mysql://10.1.2.3:3306/repair_prod username: repair_app password: ${DB_PASSWORD} redis: host: ${REDIS_HOST} port: 6379 logging: level: root: WARN com.community.repair: INFO

这里application.yml中定义了${DB_HOST}等占位符，但是application-prod.yml里直接写了10.1.2.3。因为 prod 环境的这个值比较固定，可以直接覆盖。如果连这个都希望完全动态，可以继续用${PROD_DB_URL}占位符。我的习惯是保留一层环境变量覆盖，保证安全性和灵活性兼得。

6.3 核心切面代码全览

把报修平台里用到的两个核心切面放在一起看，你就能直观感受到 AOP 的威力：

@Aspect @Component @Order(10) public class RepairOrderAuditAspect { private final RepairOrderLogMapper logMapper; public RepairOrderAuditAspect(RepairOrderLogMapper logMapper) { this.logMapper = logMapper; } @Pointcut("@annotation(com.community.repair.aspect.AuditLog)") public void auditPointcut() { } @Around("auditPointcut() && @annotation(auditLog)") public Object auditAround(ProceedingJoinPoint pjp, AuditLog auditLog) throws Throwable { long start = System.currentTimeMillis(); String operatorId = SecurityUtils.getCurrentUserId(); String operatorName = SecurityUtils.getCurrentUserName(); Object[] args = pjp.getArgs(); String methodName = pjp.getSignature().getName(); RepairOrderLog entity = new RepairOrderLog(); entity.setAction(auditLog.action()); entity.setTargetType(auditLog.targetType()); entity.setOperatorId(operatorId); entity.setOperatorName(operatorName); entity.setMethodName(methodName); entity.setRequestData(JSON.toJSONString(args)); entity.setCreateTime(new Date()); try { Object result = pjp.proceed(); entity.setResultStatus("SUCCESS"); entity.setCostTimeMs(System.currentTimeMillis() - start); logMapper.insert(entity); return result; } catch (Throwable e) { entity.setResultStatus("FAILED"); entity.setCostTimeMs(System.currentTimeMillis() - start); entity.setErrorMsg(e.getMessage()); logMapper.insert(entity); throw e; } } }

@Aspect @Component @Order(20) public class MethodPerformanceAspect { private static final Logger log = LoggerFactory.getLogger(MethodPerformanceAspect.class); @Around("execution(* com.community.repair.service.*.*(..))") public Object logPerformance(ProceedingJoinPoint pjp) throws Throwable { String methodName = pjp.getSignature().toShortString(); long start = System.nanoTime(); try { return pjp.proceed(); } finally { long costMs = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start); if (costMs > 200) { // 超过 200ms 的慢方法记录到日志 log.warn("slow method detected: {}, cost {} ms", methodName, costMs); } } } }

两个切面的@Order我会特别注意：审计切面@Order(10)，性能监控@Order(20)。当同一个方法被多个切面拦截时，@Order值小的先执行。这里让审计先执行、性能监控后执行，保证审计日志记录的是包含性能监控开销在内的完整操作耗时，对我的监控目标更合理。

6.4 报修提交接口的完整链路

最后走一遍完整链路：业主提交报修单，这个操作实际经历了哪些 AOP 增强？

调用流程是这样的：

1. 请求进入RepairOrderController.submitOrder()。
2. RepairOrderService.submitRepairOrder()方法被翻译，此时两个切面按@Order顺序执行：审计切面先记录开始时间和操作人，性能监控切面记录方法调用时间。
3. 进入业务方法本体：创建订单、保存到数据库、计算初始状态。
4. 方法返回，审计切面记录成功状态和耗时，插入repair_order_log表。
5. 如果服务抛出异常，审计切面在 catch 块中记录失败原因和异常信息。

这样一次提交操作，不需要业务方法里写任何日志、监控代码，但是日志、监控数据全部完整落到库里。这就是 AOP 的价值：让业务代码只关心业务，让横切关注点统一由切面承担。

7. 关于 AOP 的延伸：面向切面的更多可能性

做完了报修平台这个项目，我对 AOP 的使用边界也有了更深的理解。Spring AOP 最擅长的领域其实是"业务逻辑的外围"，比如日志、权限、校验、监控、缓存、重试、幂等、分布式锁。这些逻辑的共同特征是：不关心业务结果的具体内容，只关心方法执行的时机、参数、返回结果，以及异常情况。因此，在你设计切面时，一定要避免把业务判断写在切面里，否则切面会变得十分沉重，失去"轻量横切"的意义。

关于 Spring AOP 的局限，我也顺便提一嘴：它有跨类调用失效、性能损耗（动态代理）、只能拦截 Spring 容器管理的 Bean 等问题。如果你要对非 Spring 管理的对象做增强，或者要处理更细粒度的控制，可以学一下 AspectJ 的静态织入方式。选择方案的关键还是看应用场景：小型单体项目用 Spring AOP 足够了，大型复杂系统再考虑引入全量 AspectJ。

8. 项目中踩过的坑和我的最终体会

最后分享几个我在实践中的独家体会，都是代码之外的认知。

关于外部化配置，我最大的体会是：配置管理能力决定系统的上线效率。如果一个部署流程需要修改配置文件才能切换环境，这个流程一定还有优化空间。好配置设计的标准是：同一份构建产物，放到任何环境都能正确运行，差异完全由外部输入（环境变量、配置中心、启动参数）决定。这是"12-factor app"的原则，也是我评估一个项目配置能力做得好不好的标准。

关于 AOP，我最大的经验教训是：AOP 是强约定，需要团队有统一的规范。切面的好处是把横切逻辑集中管理，但它也把拦截逻辑从业务代码中抽离了，理解代码需要额外的心智成本。如果一个团队没有统一约定哪些方法会被 AOP 拦截、切面里做了什么、顺序是什么，后续维护的人很容易一脸茫然。我在项目里专门写了一份"切面清单"文档，罗列了项目中的所有 AOP 切面、作用范围、执行顺序，并要求新增切面必须更新文档，这个投入帮后来者节省了大量排查时间。

还有一个实用小技巧：开发环境下配置多个 profile 自动切换时，可以把本机 preferred profile 写进 IDEA 的 Run Configuration 里，而不是每次启动都拼参数。配合 SpringBoot3 的spring.profiles.group分组配置，能把 dev、test、prod 的环境适配配置清晰地组织起来：

spring: profiles: group: dev: common-dev,db-local,cache-local prod: common-prod,db-prod,cache-prod

这样启动时--spring.profiles.active=dev就会一次性激活common-dev、db-local、cache-local三个配置片段，模块化程度更高。

社区报修平台这个系统本身不算复杂，但通过外部化配置和 AOP 两个技术点的组合，把"配置灵活"和"逻辑整洁"这两个软件工程的重要命题真正落地了。如果你也在做类似的业务系统，希望这篇实战记录能给你一些参考，尤其是避坑部分，几乎都是我在真机环境里跑出来的教训，照着检查一遍，能少走很多弯路。