架构与系统设计 / 系统课时
渠道账单获取
渠道账单获取
本课完成一条可落地的渠道账单获取链路:从渠道地址下载文件,校验内容完整性,安全解压账单,并把原始压缩包归档,最终得到可供后续对账解析的稳定输入。
学习目标
- 设计可重试、可追踪的账单下载与落盘流程
- 使用 SHA-256 校验文件完整性并阻断损坏账单
- 安全解压 ZIP 文件并保留不可变的原始账单
获取链路与目录约定
账单获取不应直接写入正式目录。下载阶段先写入临时文件,校验通过后再进入解析阶段;只有解压成功,原始压缩包才移动到归档目录。这样可以区分“下载中”“待处理”“已归档”三种状态,避免半文件被重复消费。

生产目录通常按渠道和账单日期分层,例如 archive/<channel>/<billDate>/。文件名应包含渠道、账单日期和校验值摘要,确保同一账单重复下载时能够识别,而不是依赖覆盖写入。
最小可运行实现
下面示例使用 JDK 17 的 HttpClient 下载 ZIP,校验 SHA-256 后解压并归档。将代码保存为 ChannelBillFetcher.java,再使用 javac ChannelBillFetcher.java && java ChannelBillFetcher <URL> <SHA256> <PATH> 运行,其中动态地址和路径以实际环境为准。
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
public class ChannelBillFetcher {
public static void main(String[] args) throws Exception {
if (args.length != 3) {
throw new IllegalArgumentException("Usage: <URL> <SHA256> <PATH>");
}
URI uri = URI.create(args[0]);
String expectedSha256 = args[1].toLowerCase();
Path root = Path.of(args[2]).toAbsolutePath().normalize();
Path tempDir = Files.createDirectories(root.resolve("temp"));
Path parsedDir = Files.createDirectories(root.resolve("parsed"));
Path archiveDir = Files.createDirectories(root.resolve("archive"));
Path tempFile = tempDir.resolve("channel-bill.zip.part");
HttpRequest request = HttpRequest.newBuilder(uri).GET().build();
HttpResponse<Path> response = HttpClient.newHttpClient().send(
request,
HttpResponse.BodyHandlers.ofFile(tempFile)
);
if (response.statusCode() != 200) {
Files.deleteIfExists(tempFile);
throw new IOException("Download failed, status=" + response.statusCode());
}
String actualSha256 = sha256(tempFile);
if (!actualSha256.equals(expectedSha256)) {
Files.deleteIfExists(tempFile);
throw new IOException("Checksum mismatch");
}
int parsedFiles = unzipSafely(tempFile, parsedDir);
Path archivedFile = archiveDir.resolve("channel-bill.zip");
Files.move(tempFile, archivedFile, StandardCopyOption.REPLACE_EXISTING);
System.out.println("downloaded and archived: " + archivedFile);
System.out.println("parsed files: " + parsedFiles);
}
private static String sha256(Path file) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
try (InputStream input = Files.newInputStream(file)) {
byte[] buffer = new byte[8192];
int length;
while ((length = input.read(buffer)) >= 0) {
digest.update(buffer, 0, length);
}
}
return HexFormat.of().formatHex(digest.digest());
}
private static int unzipSafely(Path zipFile, Path targetDir) throws IOException {
int count = 0;
try (ZipInputStream zip = new ZipInputStream(Files.newInputStream(zipFile))) {
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
Path target = targetDir.resolve(entry.getName()).normalize();
// 阻止 ../ 路径穿越写出目标目录
if (!target.startsWith(targetDir)) {
throw new IOException("Illegal zip entry: " + entry.getName());
}
if (entry.isDirectory()) {
Files.createDirectories(target);
} else {
Files.createDirectories(target.getParent());
Files.copy(zip, target, StandardCopyOption.REPLACE_EXISTING);
count++;
}
zip.closeEntry();
}
}
return count;
}
}预期输出
downloaded and archived: <PATH>/archive/channel-bill.zip
parsed files: 2parsed files 取决于压缩包内的实际文件数。若状态码不是 200、摘要不一致或 ZIP 条目试图越过目标目录,程序会停止处理,避免错误账单进入后续流水线。
重试与幂等控制
下载任务的幂等键建议使用“渠道编码 + 账单日期 + 文件类型”。重试前先查询任务状态:已成功归档则直接返回;下载失败可以重试;校验失败应记录渠道响应头、文件大小和实际摘要,并进入人工处理,而不是无限重试同一损坏文件。
网络重试只覆盖连接超时、读取超时和部分 5xx 响应。鉴权失败、参数错误和账单尚未生成通常需要延后调度或修正请求,不应立即高频重试。
验收检查
完成后应检查三个结果:归档目录存在原始 ZIP,解析目录只包含目标目录内的文件,任务记录保存渠道、账单日期、文件大小、SHA-256、下载时间和最终状态。任选一个归档文件重新计算摘要,结果应与任务记录一致。