* Token 一次消费：每个 token 只能用一次，消费后立即失效 * API 文档地址：http://服务地址:9002/doc.html → "对外开放API" 分组 */ @Slf4j @RestController @RequestMapping("/zgapi/v1/open") @RequiredArgsConstructor @Tag(name = "对外开放API", description = "使用 systemCode 获取一次性 Token，Token 消费后立即失效。文档: /doc.html") public class OpenApiController { private final SysSystemMapper sysSystemMapper; private final EmailService emailService; private final FileService fileService; private final SysEmailLogMapper emailLogMapper; private final SysOpenTokenLogMapper openTokenLogMapper; private final JwtUtil jwtUtil; private final RedisUtil redisUtil; private static final int OPEN_TOKEN_TTL_MINUTES = 720; // 12小时 // ==================== Token 获取 ==================== /** * 获取一次性 API Token *
* 每个 Token 只能消费一次（调用任意 /zgapi/v1/open/* 接口即为消费），消费后立即失效。
* Token 有效期 2 小时，过期未消费也会失效。
*/
@PostMapping("/token")
@Operation(summary = "获取一次性API Token",
description = "传入 systemCode 换取 JWT Token。Token 有效期2小时，只能消费一次，消费后立即失效。")
public Result
* 仅检查 Token 是否存在且未被消费，不做消费标记。
* 用于调用方在实际调用前预先确认 Token 可用。
*/
@PostMapping("/token/validate")
@Operation(summary = "校验Token是否有效（不消费）",
description = "传入 token 检查是否存在且未被消费。注意：此接口不会消费 Token，仅做状态查询。")
public Result
* 外部系统在自己的业务中消费了 Token 后，调用此接口告知网关标记已消费，
* 防止该 Token 被重复使用。
*/
@PostMapping("/token/consume")
@Operation(summary = "标记Token已消费",
description = "外部系统调用此接口主动标记 Token 已消费。Token 被标记后不可再使用。")
public Result
* 只有邮件发送成功后才消费 Token，发送失败不消费允许重试。
*/
@PostMapping("/email/send")
@Operation(summary = "发送邮件（消费Token）",
description = "调用此接口将消费 Token，Token 只能用一次。邮件发送成功后 Token 立即失效，发送失败不消费 Token。")
public Result sendEmail(HttpServletRequest request) {
// 第1步：验证 Token（不消费，只校验有效性）
String tokenId = validateOpenToken(request);
if (tokenId == null) {
return Result.fail(401, "Token 无效或已消费");
}
// 第2步：读取请求体，兼容 UTF-8/GBK 编码
Map
* Token 通过 multipart form 字段传递。上传成功后消费 Token。
*/
@PostMapping("/file/upload")
@Operation(summary = "上传文件（消费Token）",
description = "上传文件到文件对象存储。Token 作为 form 字段传递，上传成功后立即消费 Token。")
public Result
* Token 通过 query 参数传递。下载成功后消费 Token。
* 直接输出文件二进制流，设置 Content-Disposition 触发浏览器下载。
*/
@GetMapping("/file/{id}/download")
@Operation(summary = "下载文件（消费Token）",
description = "下载文件对象存储中的文件。Token 通过 ?token=xxx 参数传递，下载成功后立即消费 Token。")
public void downloadFile(@PathVariable String id,
@RequestParam("token") String token,
HttpServletRequest request,
HttpServletResponse response) throws IOException {
// 1. 验证 Token
String tokenId = validateOpenTokenFromValue(token);
if (tokenId == null) {
response.setContentType("application/json;charset=UTF-8");
response.setStatus(401);
response.getWriter().write(JSONUtil.toJsonStr(Result.fail(401, "Token 无效或已消费")));
return;
}
// 2. 查询文件
SysFile sf = fileService.getById(id);
if (sf == null) {
response.setContentType("application/json;charset=UTF-8");
response.setStatus(404);
response.getWriter().write(JSONUtil.toJsonStr(Result.fail(404, "文件不存在")));
return;
}
// 3. 读取磁盘文件
java.nio.file.Path diskPath = fileService.getDiskPath(sf);
if (!java.nio.file.Files.exists(diskPath)) {
response.setContentType("application/json;charset=UTF-8");
response.setStatus(404);
response.getWriter().write(JSONUtil.toJsonStr(Result.fail(404, "文件不存在")));
return;
}
byte[] data = java.nio.file.Files.readAllBytes(diskPath);
// 4. 下载成功 → 消费 Token
consumeToken(tokenId);
recordConsumption(tokenId, request, "/zgapi/v1/open/file/" + id + "/download");
// 5. 输出文件流
String safeName = "download" + ext(sf.getFileName());
String encodedName = URLEncoder.encode(sf.getFileName(), StandardCharsets.UTF_8)
.replace("+", "%20");
response.setContentType("application/octet-stream");
response.setHeader(HttpHeaders.CONTENT_DISPOSITION,
"attachment; filename=\"" + safeName + "\"; filename*=UTF-8''" + encodedName);
response.setContentLengthLong(data.length);
response.getOutputStream().write(data);
response.getOutputStream().flush();
}
private static String ext(String name) {
if (name == null) return "";
int i = name.lastIndexOf('.');
return i > 0 ? name.substring(i) : "";
}
// ==================== 私有方法 ====================
/**
* 验证 Open API Token 有效性（不消费）
* 仅校验 JWT 合法性 + Redis 中存在且未被消费，不做消费标记
*/
private String validateOpenToken(HttpServletRequest request) {
String authHeader = request.getHeader("Authorization");
if (authHeader == null || !authHeader.startsWith("Bearer ")) return null;
String token = authHeader.substring(7);
try {
io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
String tokenId = jwtUtil.getTokenId(claims);
if (tokenId == null) return null;
// 检查 Redis 中 token 是否存在
if (!redisUtil.exists("open:token:" + tokenId)) return null;
// 检查是否已消费
String consumedKey = "open:token:" + tokenId + ":consumed";
if (redisUtil.exists(consumedKey)) return null;
return tokenId;
} catch (Exception e) {
return null;
}
}
/**
* 消费 Token（标记为已消费，业务操作成功后调用）
*/
private void consumeToken(String tokenId) {
redisUtil.set("open:token:" + tokenId + ":consumed", "1", OPEN_TOKEN_TTL_MINUTES, TimeUnit.MINUTES);
}
/**
* 记录 Token 消费日志
*/
private void recordConsumption(String tokenId, HttpServletRequest request, String api) {
try {
SysOpenTokenLog log = new SysOpenTokenLog();
log.setTokenId(tokenId);
log.setConsumed(1);
log.setConsumedAt(LocalDateTime.now());
log.setConsumeApi(api);
log.setConsumeIp(IpUtil.getClientIp(request));
// 根据 tokenId 更新记录
LambdaQueryWrapper 用于 token 不在 Authorization 头的场景（如 form 字段、query 参数）
*/
private String validateOpenTokenFromValue(String token) {
if (token == null || token.isEmpty()) return null;
try {
io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
String type = claims.get("type", String.class);
if (!"open_api".equals(type)) return null;
String tokenId = jwtUtil.getTokenId(claims);
if (tokenId == null) return null;
// 检查 Redis 中 token 是否存在且未被消费
if (!redisUtil.exists("open:token:" + tokenId)) return null;
if (redisUtil.exists("open:token:" + tokenId + ":consumed")) return null;
return tokenId;
} catch (Exception e) {
return null;
}
}
/**
* 从 HttpServletRequest 读取 JSON 请求体，自动检测 UTF-8/GBK 编码
*/
@SuppressWarnings("unchecked")
private Map