基于微服务架构的校园社团签到系统：SpringBoot+Vue+小程序实战

社团签到这活儿，办过活动的人都懂：纸面签到效率低下、代签现象严重，活动结束后统计出勤名单还得人工录入Excel，遇到Excel版本不兼容直接白干。这学期帮学校社团联合会做了个校园学生社团签到系统，技术栈选了 SpringBoot + Vue + Spring Cloud 微服务架构，小程序端负责学生签到，管理后台负责社团与活动管理，再把签到数据用图表可视化呈现，这套组合跑完整个学期，基本实现了从"登记表"到"数据看板"的切换。下面把整个项目的架构思路、关键实现和踩坑记录梳理一遍，给准备做类似项目的同学一个可以直接参考的版本。这篇文章适合有 Java 和 Vue 基础、想了解微服务如何落地到真实业务的读者，也适合准备把类似课题作为课程设计或毕业设计的在校生。

1. 从真实需求出发：为什么签到系统要上微服务

1.1 签到业务的真实痛点

先说业务背景。校园里的社团数量多，每个社团每周有常规活动、例会、训练，大活动时还有跨社团联合签到。传统流程是活动负责人打印签到表，参与者自己签名，结束后负责人拍照上传微信群，再由办公室同学人工录入。这套流程的痛点集中在几个地方：

一是代签没法防。签名靠自觉，一张表传下去，经常出现一个人签一排名字的情况。二是统计链条太长。活动结束到数据可查，中间隔了录入、核对、汇总好几道人工工序，往往要两三天才能给出准确的出勤名单，很多社团根本坚持不下来做长期数据分析。三是信息不透明。成员自己不知道参加了几次活动、差几次才达标，负责人想汇总活动效果也没有直观数据。

这个系统的核心目标就是把这几个痛点一起解决：用小程序完成签到和查看个人记录，用管理后台维护活动与签到记录，最后用可视化面板让数据主动说话。所以项目标题里的"签到系统"和"可视化"不是两个独立功能，可视化本身就是签到数据的二次价值提炼。

1.2 微服务架构在这个场景下的取舍

一个签到系统，看起来功能不多，为什么非要上 Spring Cloud 微服务？这是很多人第一眼会问的问题。我说实话，如果只是单个社团内部用，单体应用就够了，甚至一个 Spring Boot 项目加一张 Activity 表、一张 SignRecord 表就能跑通。但放在校园社团联合会这个规模上，业务会逐步分化出用户认证、社团管理、活动管理、签到记录、数据统计等多个领域，而且后续大概率还要接消息通知、活动积分、第二课堂学分等功能，单体应用的代码边界会越来越模糊。

另一个更实际的原因是学习与架构升级的考量。学生社团系统往往是高校计算机专业项目、毕业设计、实验室课题的重灾区，在这些场景里，选微服务架构本身就包含了一部分技术学习的目标——让大家真正跑一遍注册中心、网关、服务调用和分布式配置，而不是停留在理论课的 PPT 里。这个项目用到的微服务组件不算多，但足以覆盖注册发现、网关路由、服务间调用、流量治理这几条主干线，属于"务实型微服务"，不是拿着大炮打蚊子。

不过这里要泼一盆冷水：别为了微服务而微服务。如果你只是做一个几百人规模、单社团使用的签到，老老实实单体应用更务实。当你有多个社团、多种活动、管理者与成员角色分离、还要做统计看板的时候，微服务的拆分价值才开始体现。下面这套方案，就是按照后一种场景来设计的，看完你就知道每拆一个服务解决的是什么问题。

2. 整体技术选型与架构设计

2.1 后端：SpringBoot + Spring Cloud 组件怎么选

后端主框架用 Spring Boot 2.7.18，Spring Cloud 用 2021.0.8 版本，Spring Cloud Alibaba 用 2021.0.5.0。为什么用这个版本组合？因为这是微服务项目中坑最少的搭配。Spring Boot 3.0 之后包名从 javax 改成 jakarta，很多网上教程和插件还停留在旧写法，写起来容易踩雷；Spring Cloud 版本太新又容易出现组件兼容问题。你这个项目如果用毕业设计答辩，老师大概率会问版本选型，能说清楚"版本对应关系"本身就是加分项。

注册中心直接用 Nacos。相比 Eureka，Nacos 同时具备注册中心和服务配置中心的功能，可以少部署一个 Config Server，对资源紧张的学生服务器很友好。服务间调用用 OpenFeign，网关用 Spring Cloud Gateway。限流和熔断用 Sentinel，主要是给高频签到接口做个保护，防止活动开始那一刻几百人同时提交导致接口被打挂。

数据库用 MySQL 8.0，缓存用 Redis。Redis 在这里的作用有两个：一是保存登录 token，小程序端每次请求带上 token，网关做统一鉴权；二是缓存活动签到配置，比如允许签到的地理位置和签到码，避免每次签到请求都去查数据库。这套组合在社区社团规模下完全够用，也方便后续扩展。

2.2 管理端与小程序的框架选择

管理后台用 Vue 3 + Element Plus。Vue 3 的 Composition API 在写图表联动、表格筛选这类复杂交互时逻辑更集中，不用像 Options API 那样把同一个功能的代码拆到 data、methods、watch 三个地方。组件库选 Element Plus 是因为它和 Vue 3 配合成熟，后台管理需要的表格、表单、弹窗、上传组件都现成，遇到问题搜解决方案也快。

小程序端用 uni-app 开发，编译成微信小程序。这里多说一句为什么不用原生微信小程序：一是 uni-app 的语法接近 Vue，和后台管理端共用一套技术认知，团队成员切换成本低；二是以后如果要出抖音小程序、支付宝小程序，同一套代码改改就能发。如果你只是做微信生态，原生小程序也没问题，但 uni-app 的跨端能力在这个项目里是实打实的收益。

项目标题里的"小程序"和"Vue"并不是割裂的两条线，它们共享了后端的接口契约和大部分数据格式约定。我在管理后台把接口文档用 springdoc-openapi 生成好，小程序端直接按接口文档对接，两边并行开发不互相等。

2.3 可视化方案：大屏和页面图表怎么落

可视化部分没有引入重型 BI 工具，直接用的 ECharts。ECharts 的图表类型覆盖面足够广，配置项灵活，社区资料多，出现问题搜一下基本都有答案。管理后台里用到了折线图（签到趋势）、柱状图（各社团活动数量）、饼图（参与率构成）、雷达图（成员活跃度）。如果要做大屏展示，建议用 DataV 或者直接把 ECharts 放在深色背景的页面里，配合 CSS 实现底部光感和边框动画，效果不比现成大屏组件差，而且自己写的布局可控性更强。

图表数据源不要直接让前端调业务库表。我在统计服务里封装了专门的聚合接口，前端一次性拿到已经聚合好的 JSON 数据，渲染速度快，也不至于把业务库的查询压力暴露给可视化页面。这个设计决策在后面部署上线时体现出了价值——签到高峰期启动活动时，可视化页面和大屏展示完全没有被拖慢。

3. 服务拆分与多 Module 工程搭建

3.1 服务边界划分：六个业务线

这个项目分为六个服务，其中数据库独立给核心业务使用，避免服务之间跨库查询：

用户服务负责微信登录换取 token，同时维护成员与社团的绑定关系；社团服务负责社团的创建、解散、成员审核；活动服务发布活动，并把活动关联到社团；签到服务是核心，负责生成签到二维码、校验位置和时间、写入签到记录；统计服务通过定时任务把明细数据聚合成统计结果。整个业务链是这样流转的：成员在小程序看到活动列表，点击报名，活动现场扫签到码，后台记录签到，统计服务定期汇总，管理端展示可视化报表。

这里特意把签到服务独立出来，是因为它是整个系统里并发压力最大、对数据一致性要求最高的部分。签到高峰期几百个学生同时操作，如果和其他业务混在一个服务里，一次 Full GC 就能让整个后台卡住。独立部署之后，即使签到服务负载高，管理后台的社团管理、活动发布等功能仍然不受影响。

3.2 父工程搭建：Maven 多 Module 结构

工程采用 Maven 多 Module 结构。父 pom 只做依赖管理，子模块之间不互相依赖，通过注册中心发现服务。创建工程的顺序是：先用 Spring Initializr 生成父工程，然后逐个创建子 Module，每个子 Module 都是一个独立的 Spring Boot 应用。

目录结构如下：

code复制club-sign-system/
├── pom.xml                       # 父工程，统一管理依赖版本
├── gateway-server/               # 网关服务 8080
├── user-service/                 # 用户服务 8081
├── club-service/                 # 社团服务 8082
├── activity-service/             # 活动服务 8083
├── sign-service/                 # 签到服务 8084
└── stats-service/                # 统计服务 8085

每个服务的代码结构保持统一：controller、service、mapper、entity、config 五个包。看起来简单，但对参与项目的同学来说，统一结构意味着"学会一个服务等于学会所有服务"，维护成本低很多。团队里新同学接手时不用重新理解一套代码组织方式，上手速度明显快。

3.3 版本对应关系与核心配置

版本问题是最容易翻车的地方，单独拿出来说。Spring Boot 2.7.x 对应的 Spring Cloud 版本是 2021.0.x（也叫 Jubilee），对应的 Spring Cloud Alibaba 版本是 2021.0.5.0。这里的坑在于：Spring Cloud Alibaba 的版本号不跟 Spring Cloud 走，Nacos 客户端版本也有自己的节奏。最简单的做法是直接去 Spring Cloud Alibaba 官方仓库看版本说明，别自己猜。

父 pom 核心依赖：

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
    <relativePath/>
</parent>

<properties>
    <spring-cloud.version>2021.0.8</spring-cloud.version>
    <spring-cloud-alibaba.version>2021.0.5.0</spring-cloud-alibaba.version>
</properties>

每个业务服务的配置都以 Nacos 注册中心为核心，以 user-service 为例：

yaml复制spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/club_user?useUnicode=true&characterEncoding=utf8
    username: root
    password: 你的密码
  redis:
    host: 127.0.0.1
    port: 6379

server:
  port: 8081

网关配置路由时，重点是前缀的剥离。比如小程序端请求 /api/user/login，网关会去掉 /api 前缀，转发到 user-service 的 /user/login。这样前端不用关心服务拆分的细节，只认为后端是一个整体。这个约定要在项目一开始就定死，后面加新服务都按同一套规则接入，路由配置才不会被绕晕。

4. 核心签到流程：小程序端到后端的完整链路

4.1 登录与鉴权：token 怎么管理

小程序端第一次打开时调用 wx.login 获取 code，后端把 code 发给微信接口换 openid，查询 user-service 里是否已有这个用户，没有就自动注册，有就直接登录。登录成功后生成 token，存到 Redis，key 是 token，value 是用户 id 和角色信息，过期时间七天。小程序端把 token 放在请求头的 Authorization 字段里，后续所有接口都带这个 token。

网关的全局过滤器会拦截所有请求，白名单路径比如 /api/user/login、/api/user/wx-login 直接放行，其他请求校验 token 是否存在且有效。为什么把 token 校验放在网关而不是每个服务里？因为如果每个服务各自写一套鉴权逻辑，改一个校验规则就要改六个服务，网关统一处理一次就够了。服务内部如果需要知道当前用户是谁，可以约定网关把用户 id 放进请求头，比如 X-User-Id，服务间再用 OpenFeign 调用时把用户上下文透传过去。

网关过滤器这里还要注意一个细节：校验 token 时只查 Redis 里 key 是否存在，不要每次都反序列化整个用户对象。我一开始图省事把用户信息全量序列化成 JSON 存进 Redis，结果每次请求都多消耗几毫秒，活动高峰时积少成多，CPU 使用率明显偏高。后来改成网关只取 user id，服务内部需要详情再调用 user-service 查询。

4.2 签到接口核心实现：位置校验 + 签到码

签到场景有两种：一种是线下活动现场，活动负责人展示签到码，成员用小程序扫码签到；另一种是线上活动，成员在小程序里点击"签到"按钮，后台校验位置。

线下扫码的核心代码如下。签到时先解析二维码里的 activityId 和 signToken，再拿着 activityId 查 sign-service 里存的活动签到配置，拿到允许签到的经纬度和有效期，然后用 Haversine 公式计算用户当前位置和活动地点的距离，距离在允许范围内才允许签到。

java复制public SignResult sign(SignRequest request) {
    // 1. 校验签到码是否有效
    SignConfig config = signConfigMapper.selectByActivityId(request.getActivityId());
    if (config == null || !config.getSignToken().equals(request.getSignToken())) {
        return SignResult.fail("签到码无效");
    }

    // 2. 校验签到时间是否在有效期内
    if (LocalDateTime.now().isBefore(config.getStartTime())
            || LocalDateTime.now().isAfter(config.getEndTime())) {
        return SignResult.fail("不在签到时间范围内");
    }

    // 3. 校验地理位置
    double distance = GeoUtils.calculateDistance(
            request.getLatitude(), request.getLongitude(),
            config.getLatitude(), config.getLongitude());
    if (distance > config.getAllowRadius()) {
        return SignResult.fail("您距离活动地点太远，无法签到");
    }

    // 4. 防重复签到，数据库唯一索引兜底
    try {
        signRecordMapper.insert(SignRecord.from(request));
        return SignResult.success("签到成功");
    } catch (DuplicateKeyException e) {
        return SignResult.fail("您已签到，请勿重复操作");
    }
}

GeoUtils 里的 Haversine 公式实现不复杂，就是把两个点的经纬度转成弧度，套公式算出球面距离，单位是米。这个公式在几百米的签到场景下精度足够，别用简单的勾股定理，因为经纬度不是平面坐标，直接算会偏得离谱。Java 实现就是 Math 库的三角函数组合，网上能搜到现成代码，但建议理解之后再复制，面试时被追问到也好解释。

4.3 防作弊设计：不能只靠一个定位

签到系统最容易被钻空子的点就是代签和虚拟定位。我在设计里加了四层防线：

第一层是签到码时效性。签到码由活动创建时生成，包含随机 token，只在活动开始前半小时到结束后半小时有效，过期自动失效。这样签到码不能提前截图囤着，也无法在活动结束后补签。

第二层是地理位置校验。允许签到半径由活动负责人设置，默认 300 米。这里要特别注意，微信小程序的 wx.getLocation 在部分手机上有基站定位漂移，实测误差可能在几十米到上百米，所以半径别设太小，否则学生会因为定位漂移签到失败，客服那边全是投诉。

第三层是频控。同一个用户在同一个活动只能签到一次，数据库用 (activity_id, member_id) 建唯一索引兜底，就算并发请求绕过业务层的判断，数据库也会拦住重复写入。这一步必不可少，我一开始只做了业务层校验，压测时用 50 个并发模拟同一个用户重复签到，结果同时插入了两条记录，最后只能靠唯一索引把数据救回来。

第四层是行为风控。一个人连续签到多个不同地点的活动，或者签到时间异常（比如凌晨三点），后台会打上异常标记。这个不放在主流程里，由定时任务扫描签到记录做规则判断，避免影响正常签到体验。

4.4 小程序端页面流程：从活动列表到签到完成

小程序端主要页面包括首页活动列表、活动详情、签到页、个人中心。活动列表用分页加载，uni-app 里监听 onReachBottom 触底事件，自动请求下一页数据，当前页数据读取完毕时显示"没有更多了"。这个"加载更多"的逻辑看起来简单，但要注意加载状态的防重复触发——触底事件在快速滚动时可能连续触发多次，不加锁的话会出现重复请求和列表数据错乱。

活动详情页进入时会根据活动状态动态调整标题文字，用 uni.setNavigationBarTitle 修改顶部导航标题，让学生一眼看清楚当前处在哪个活动上下文里。签到按钮的状态也要跟着活动生命周期变化：未开始显示"活动未开始"，进行中且未签到显示"立即签到"，已签到显示"已完成"。这些状态都通过一个统一的 status 字段从后端接口拿，前端只负责渲染，不要把状态判断逻辑写在小程序里，否则后端改规则前端又要发版。

小程序端所有请求都封装在 request.js 里，自动附带 token，收到 401 状态码时清掉本地 token 并跳转登录页。网络异常时弹 toast 提示，避免用户以为签到失败又去重复点击。实测下来，活动高峰期的重复请求大多不是用户恶意操作，而是网络超时后用户不知道是否签到成功，再次点击导致的，这个交互层的引导比后端防重更有效。

5. 可视化统计与数据聚合

5.1 统计数据怎么产生：明细转聚合

签到记录的明细表会越来越大，如果可视化页面每次都去 group by 明细表，活动一多查询会越来越慢。我的做法是：统计服务每天凌晨跑一次定时任务，把前一天的活动签到数据聚合成统计表，比如每个活动的参与人数、签到率、每个成员的参与次数、每个社团的活动热度。可视化页面只查聚合表。

聚合表结构大概是这样的：stats_activity 表记录每个活动从发布到结束的完整生命周期数据，包括报名人数、签到人数、签到率、平均签到耗时；stats_member 表记录每个成员的出勤次数、最近活跃时间、连续签到天数；stats_club 表记录每个社团的活动数量和成员活跃度。这样设计的好处是查询路径短，图表接口基本是秒回。

定时任务用 Spring 自带的 @Scheduled 就能实现，不需要额外引入分布式任务调度框架。如果后期服务多实例部署，同一个定时任务会在多个实例上重复执行，到时候再考虑 XXL-Job 或者给任务加分布式锁。现在项目规模用单实例跑统计任务，凌晨两点执行，五分钟内跑完，完全够用。

5.2 ECharts 集成：Vue 里画一张签到趋势图

管理后台的图表用 ECharts 实现。先装依赖，然后按需引入图表模块，这一步很重要，直接 import * as echarts from 'echarts' 会把整个包打进去，体积大不少，按需引入能把包体积控制到一半以内。

javascript复制import * as echarts from 'echarts/core';
import { LineChart } from 'echarts/charts';
import { GridComponent, TooltipComponent } from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

echarts.use([LineChart, GridComponent, TooltipComponent, CanvasRenderer]);

图表组件的思路是：从统计服务拉取近 14 天的签到数据，渲染成折线图，x 轴是日期，y 轴是签到人数。数据格式统一成 { date: '2024-05-01', count: 42 } 这样的数组，前端拿到直接 map 成 ECharts 需要的格式。注意一个坑：ECharts 在表格页签切换或者弹窗打开时，容器可能还没渲染完成，需要在 nextTick 之后初始化，否则图表宽度会变成 0。这个问题在管理后台的路由切换场景里非常高频，我排查了好几次才发现是初始化时机的问题。

5.3 图表联动与报表导出

管理后台的可视化不只是单张图表，还有联动需求：左侧选择社团，右侧所有图表（活动数量、签到人数、活跃成员）一起刷新。实现思路是选中的社团 id 存入响应式变量，ECharts 实例监听这个变量变化，重新调用统计接口并 setOption。这里要注意销毁旧实例，否则切社团时图表会叠加显示上一轮的数据，画面非常乱。

报表导出用的是服务端 POI 生成 Excel，统计服务提供一个导出接口，直接查询聚合表数据并写出 .xlsx 文件流。为什么不用前端方案？因为前端导出需要把所有数据拉到浏览器端，数据量大时内存占用高，而且样式控制不如 POI 灵活。管理后台的表格导出按钮会请求后端接口，后端生成文件后返回下载链接，前端 window.open 触发下载。这个方案在数据量几万行的场景下实测稳定。

5.4 大数据量下的优化思路

虽然校园社团的规模用不上特别重的技术，但还是要做两个基础优化。一是签到明细表按月份做分区表，查询历史数据时能快速定位分区；二是签到写入用 Redis 做缓冲，先写 Redis 再异步同步到 MySQL，活动高峰时扛住瞬时流量。

这里的选择要克制。异步写入意味着签到记录有延迟，如果活动现场负责人想立刻看到签到人数，那我建议只在活动高峰期启用异步，平时直接同步写。我在项目里做了一个开关，配置中心改一下就能切换，既保证了实时性，又留了扩容的后路。这个设计思路比"一刀切用异步"成熟得多，因为真实业务的实时性诉求是动态变化的，不能靠一个固定方案打天下。

6. 微服务环境部署与上线流程

6.1 中间件环境准备：Nacos、MySQL、Redis

服务器内存 8G 的话，可以单机部署所有中间件和服务。先装 JDK 1.8、MySQL 8.0、Redis、Nacos。Nacos 单机模式启动命令是 sh startup.sh -m standalone，默认端口 8848。启动后打开控制台，创建命名空间把各个服务的配置和管理后台的公共配置分开。

MySQL 初始化需要注意字符集，建库时指定 utf8mb4，否则中文表情符号存不进去。初始化脚本里包含五个库：club_user、club_club、club_activity、club_sign、club_stats，对应五个业务服务。如果数据库和服务数量对不上，后面启动服务时 Nacos 能注册成功，但服务调用时就会因为找不到表而报错，这个坑我踩过一次。

6.2 服务打包与启动顺序

打包用 Maven，父工程目录下执行 mvn clean package -DskipTests，跳过测试加快构建。打包完成之后，每个服务的 jar 都在各自的 target 目录下。启动顺序有讲究：先 Nacos，再 MySQL 和 Redis，然后启动 user-service、club-service、activity-service、sign-service、stats-service，最后启动 gateway-server。

网关为什么最后启动？因为网关是流量的入口，如果先启动网关，而背后对应的服务还没注册到 Nacos，用户请求进来就会得到 503 错误。业务服务全部就绪后再启动网关，用户看到的永远是可用的后端。启动日志里看到 Nacos registered successfully 字样，说明服务注册成功。

启动命令可以写成 bash 脚本，一键按顺序拉起所有 jar 包。

bash复制#!/bin/bash
nohup java -jar user-service/target/user-service.jar --spring.profiles.active=dev > logs/user.log 2>&1 &
nohup java -jar club-service/target/club-service.jar --spring.profiles.active=dev > logs/club.log 2>&1 &
nohup java -jar activity-service/target/activity-service.jar --spring.profiles.active=dev > logs/activity.log 2>&1 &
nohup java -jar sign-service/target/sign-service.jar --spring.profiles.active=dev > logs/sign.log 2>&1 &
nohup java -jar stats-service/target/stats-service.jar --spring.profiles.active=dev > logs/stats.log 2>&1 &
nohup java -jar gateway-server/target/gateway-server.jar --spring.profiles.active=dev > logs/gateway.log 2>&1 &

6.3 多环境配置与看板构建

开发环境、测试环境、生产环境的数据库地址和 Redis 地址都不同，用 Spring 的 profile 机制解决。每个服务下放 application-dev.yml、application-test.yml、application-prod.yml，启动时通过 --spring.profiles.active 指定环境。敏感信息不要写进配置，用环境变量注入，比如数据库密码写成 ${DB_PASSWORD}，部署时在系统的环境变量里设置，避免配置文件泄露导致数据库被脱库。

可视化大屏我单独做了一个纯静态页面，部署到 Nginx 里，和后台管理应用分开。大屏页面只要图表和统计数据，不需要登录，所以放在 Nginx 的静态目录下，定时刷新聚合接口。这种方式部署成本最低，也方便在活动室里用一台电视循环展示。后台管理应用则是标准的 Vue 打包产物，build 之后 dist 目录扔给 Nginx，再配置反向代理到网关地址。

7. 常见问题与排查技巧实录

7.1 微服务联调最常见的三个坑

第一个坑是服务之间调用超时。OpenFeign 默认连接超时 1 秒，读超时 1 秒，校园网环境下慢一点就报错。排查方式很简单，先在服务日志里看是连接超时还是读超时，然后到配置里调大：

yaml复制feign:
  client:
    config:
      default:
        connect-timeout: 5000
        read-timeout: 5000

第二个坑是网关跨域。小程序端请求有域名限制不涉及跨域，但管理后台浏览器调试时，前端直接请求网关联调会出现 CORS 问题。网关里配置统一跨域过滤器，允许指定 origin 和 header，别在各个服务里分别配，不然容易出现配置冲突。我在项目里写了一个 GlobalCorsConfiguration，把 allowedOrigins 配置成管理后台的域名列表，上线后只允许特定域名访问，安全性也好一些。

第三个坑是 Nacos 注册了但服务找不到。多半是服务启动顺序的问题：先启动 Nacos，再启动各个业务服务和网关。如果仍然找不到，先看 Nacos 控制台里服务列表有没有注册成功，再看消费者用的服务名和注册中心里的服务名是否一致。服务名不一致这个问题出现的频率远超想象，因为大部分人是从文档复制配置，改配置时漏了 application.name。这个字段的大小写和空格都要完全一致，否则 OpenFeign 调用时就会报 UnknownHost 异常。

7.2 小程序端兼容与体验问题

小程序真机调试和开发工具表现不一致，最常见的是定位权限。在开发工具里 wx.getLocation 直接就能返回坐标，但真机上用户没授权时，调用会直接失败，提示用户需要在设置里打开定位权限。正确的做法是在调用定位前先检查 wx.getSetting 里的 location 权限状态，未授权时引导用户打开。

另一个高频问题是 session_key 过期。微信登录的 code 换成 openid 后，session_key 有时效，如果后端把 session_key 存进用户表并在后续请求中校验，过期后用户必须重新走登录流程。实际上我们只需要 openid 和 token，不需要保存 session_key，token 过期就让小程序端重新调 wx.login，别让用户手动退出再登录。

还有一个很多人会忽略的问题：小程序端请求的接口域名必须在微信公众平台配置 request 合法域名，否则真机预览时所有请求都被拦截，提示"不在以下 request 合法域名列表中"。开发阶段可以用"不校验合法域名"选项临时调试，但上线前一定要把 HTTPS 域名配好，光配 IP 地址或者 http 协议都会失败。

7.3 性能和并发：活动开始那一刻怎么办

活动签到的高峰通常在活动开始前后十分钟，几百人同时提交签到。网关做了 Sentinel 限流，单用户每秒最多请求两次，超过就返回友好提示。数据库层面用唯一索引防重，Redis 缓存签到配置，尽量把请求拦截在业务服务之外的环节。

实测下来，单纯做限流还不够，签到逻辑里那个 Haversine 距离计算是纯 CPU 计算，不会成为瓶颈，真正的瓶颈是签到记录表的高并发插入。解决办法是数据库连接池参数调大，并在 sign_record 表的 (activity_id, member_id) 上加唯一索引，这样即使业务层判断被并发穿透，数据库也能拦住重复签到。另外建议把签到接口的日志级别调低，活动高峰期别打 info 日志，否则日志写入本身就会消耗大量磁盘 IO 和 CPU，接口响应时间会被拖慢几百毫秒。

7.4 版本与依赖管理速查

这套系统做下来，我最真实的感受是：微服务架构真正困难的不是把 Spring Boot 项目拆成几个服务，而是把服务之间的边界和数据的流向想清楚。很多同学上来就拆服务，结果每个服务都写一套自己的用户信息逻辑，改需求的时候所有服务都要动，反而比单体更痛苦。这个项目的拆分能跑通，恰恰是因为一开始就把"谁能做什么、数据归谁管、服务之间怎么协作"定清楚了。如果你也想做类似的东西，建议先从单体把业务流程验证透，再按领域拆服务，最后再接可视化，这条路走起来最稳。

最后再分享一个过程中的小技巧：定签到半径之前，先在校园里找三五个不同位置实测一下微信定位的漂移范围。我在操场东门测出来的漂移值和教学楼门口完全不一样，直接按官方文档的建议值设置，前两周大概率会收到"我明明在现场为什么签不了"的反馈。这个项目上线之后最繁忙的不是写代码的时间，而是处理这类真实使用反馈的时间。实测数据比文档建议值靠谱，这是我做这类校园场景系统时最深刻的一个体会。