2025-09-30 17:40:10 +08:00
|
|
|
|
# mosquito
|
|
|
|
|
|
|
2026-03-02 13:31:54 +08:00
|
|
|
|
Spring Boot 3 (Java 17) 应用，用于活动传播、邀请奖励与运营分析。
|
|
|
|
|
|
|
|
|
|
|
|
快速开始
|
|
|
|
|
|
- 构建与测试：`mvn -B -DskipTests=false clean verify`（将触发 Flyway 迁移与覆盖率门禁）
|
|
|
|
|
|
- 运行（开发）：`mvn spring-boot:run`（默认 `dev` 配置）
|
|
|
|
|
|
|
|
|
|
|
|
关键端点
|
|
|
|
|
|
- 所有 JSON 响应统一为 `ApiResponse`，业务数据位于 `data` 字段。
|
|
|
|
|
|
- `/api/**` 需要 `X-API-Key`；`/api/v1/me/**`、`/api/v1/activities/**`、`/api/v1/api-keys/**`、`/api/v1/share/**` 还需要 `Authorization: Bearer <token>`。
|
|
|
|
|
|
- API 密钥
|
|
|
|
|
|
- 创建：`POST /api/v1/api-keys`
|
|
|
|
|
|
- 吊销：`DELETE /api/v1/api-keys/{id}`
|
|
|
|
|
|
- 使用（按 ID 校验并打点）：`POST /api/v1/api-keys/{id}/use`
|
|
|
|
|
|
- 使用（仅凭明文密钥，无需 ID）：`POST /api/v1/api-keys/validate`
|
|
|
|
|
|
|
|
|
|
|
|
- 用户端体验
|
|
|
|
|
|
- 邀请信息：`GET /api/v1/me/invitation-info`
|
|
|
|
|
|
- 邀请好友分页：`GET /api/v1/me/invited-friends`
|
|
|
|
|
|
- 海报图片：`GET /api/v1/me/poster/image`
|
|
|
|
|
|
- 海报 HTML：`GET /api/v1/me/poster/html`
|
|
|
|
|
|
- 海报配置：`GET /api/v1/me/poster/config`
|
|
|
|
|
|
|
|
|
|
|
|
- 缓存管理（需要管理令牌）
|
|
|
|
|
|
- 清空缓存：`DELETE /api/v1/cache/{cacheName}`
|
|
|
|
|
|
- 失效键：`DELETE /api/v1/cache/{cacheName}/{key}`
|
|
|
|
|
|
|
|
|
|
|
|
运维与安全
|
|
|
|
|
|
- 配置管理令牌：`app.cache.admin-token`（通过环境变量或配置文件注入）
|
|
|
|
|
|
- 缓存失效限流：`app.cache.rate-limit-per-minute`（默认 60）
|
|
|
|
|
|
- Redis 缓存分组 TTL（可在 `CacheConfig` 中调整）：
|
|
|
|
|
|
- `leaderboards` 5m、`activities` 1m、`activity_stats` 2m、`activity_graph` 10m
|
|
|
|
|
|
- 生产环境必须设置 `app.security.encryption-key`（例如环境变量 `APP_SECURITY_ENCRYPTION_KEY`）
|
|
|
|
|
|
- 覆盖率门禁：`pom.xml` 中启用 JaCoCo，阈值 80%，在 `verify` 阶段校验
|
|
|
|
|
|
|
|
|
|
|
|
更多接口与错误码见 `docs/api.md`。
|
