Java 发布包构建 / Java Release Packager

技能文档

---
name: java-release-packager
display_name: Java 发布包构建 / Java Release Packager
description: 为 Java/Spring Boot 后端服务打包带版本号、带清单、全幂等的发布包：累积 SQL 变更脚本 + 构建产物（jar/dist）成一个 zip。Build a versioned, deployable release package for a Java or Spring Boot backend service by accumulating idempotent SQL change scripts and build artifacts into one zip with a release manifest. 触发词：打包发版、发布包、版本化构建、SQL 累积、release package。
summary_zh: 把后端服务的数据库变更脚本 + 构建产物打包成带版本号、带清单、全幂等的可部署发布包。
summary_en: "Package a backend service's SQL change scripts and build artifacts into a versioned, manifest-backed, fully idempotent deployable release bundle."
version: 1.0.0
category: automation
tags: [java, spring-boot, release, deploy, sql, automation]
---

# java-release-packager

把"为后端服务做版本化发布包"的高频流程固化为可复用方法：从一组 SQL 变更脚本 + 构建产物（jar / dist）生成一个**带版本号、带 manifest、全幂等**的可部署 zip。

适用任何用构建工具（Maven / Gradle）的 Java 后端服务，与具体业务无关——可套到会员中心、订单系统、内容平台等任意后端。

## 简介 / Introduction

**中文**：把"为后端服务做版本化发布包"的流程固化成可复用方法：从一组 SQL 变更脚本 + 构建产物（jar/dist）生成一个带版本号、带 manifest、全幂等的 zip。与业务无关，可套到任意 Java/Spring Boot 后端。

**English**: Turns the "build a versioned release package for a backend service" flow into a reusable method: gather SQL change scripts plus build artifacts (jar/dist) into a versioned, manifest-backed, idempotent zip. Business-agnostic; works for any Java/Spring Boot backend.

## 何时用

- 要把一次迭代的数据库变更 + 后端构建产物打包成一个可上线发布包
- 测试 / 预发 / 生产多个环境要共用同一份发布包，靠版本号追溯
- 想让"SQL 早于代码部署""脚本全幂等"等铁律变成可检查的清单

## 核心原则（铁律）

1. **版本号唯一且单调**：一个发布包对应唯一版本号（如 `2026.09.03.1`），一经发布不回退、不复用。
2. **SQL 部署早于代码**：发布包内 SQL 必须在 jar/dist 之前执行；任何部署流程都先落库再换产物。
3. **变更脚本全幂等**：每条 SQL 必须可重复执行无副作用（用 `IF NOT EXISTS`、幂等 DDL、幂等 INSERT）。发布包可多次重放。
4. **累积未执行脚本**：凡是"应执行但未执行"的变更脚本，一律累积进最新发布包（不要只放本次新增）。
5. **备份先于一切**：部署发布包前先做整库备份；备份失败则中止。
6. **manifest 随包走**：zip 内附 manifest（版本、时间戳、文件清单、每个文件 md5），便于审计与回滚定位。

## 分步流程

1. 确定本次版本号（基于上一包 +1，或日期戳递增）。
2. 扫描变更脚本目录，按文件名顺序收集全部 `.sql`（含历史未执行项）。
3. 收集构建产物（jar / dist），确认与版本号对应。
4. 生成 manifest：版本、UTC 时间戳、文件清单、各文件 md5。
5. 用 zipfile 打包（`scripts/build_release_pkg.py`），根目录含 `release/` 与 `manifest.json`。
6. 本地解包自检：结构正确、manifest 可读、SQL 可 dry-run（幂等检查）。
7. 上传到发布通道，触发部署（部署侧先备份 → SQL → 产物）。

## 坑（来自真实事故）

- **只放本次新增 SQL**：漏掉历史未执行脚本 → 生产缺表/缺列 → 启动即 500。必须累积。
- **脚本非幂等**：重放发布包时重复建表或插重复数据 → 部署中途报错。
- **版本号回退**：用旧版本号重新发包 → 环境间包冲突、追溯失效。
- **临时文件进包**：把本地顶层 dump 或中间产物误打进 zip → 体积爆炸 + 路径泄露。
- **SQL 晚于产物**：先换 jar 再跑 SQL → 新代码读不到新表 → 启动崩溃。

## 骨架脚本

`scripts/build_release_pkg.py`：参数化，给定 sql 目录、产物目录、版本号、输出目录，自动收集 + 打包 + 生成 manifest。改配置即可用，无业务耦合。

## 验收清单

见 `references/acceptance-checklist.md`（7 条，上架/改版前必跑）。

## 触发词

上线、打包、发布包、版本化构建、SQL 累积、release package、build release bundle。

使用说明

## 解决什么问题

为 Java / Spring Boot 后端服务构建版本化、可回滚的发布包：把一组 SQL 变更脚本与构建产物（jar / dist）打包成带版本号、带 manifest、全幂等的可部署 zip。

## 核心铁律

- **版本号唯一且单调**：不可重号、不可倒退。
- **SQL 部署早于代码**：变更脚本先跑，新 jar 才能假定 schema 已就绪。
- **变更脚本全幂等**：同一脚本重复执行结果一致（CREATE TABLE IF NOT EXISTS、INSERT ... ON DUPLICATE KEY 等）。
- **累积未执行脚本**：每次打包把上线遗漏的 SQL 一并携带。
- **备份先于一切**：打包/部署脚本里强制先落库或文件备份。
- **manifest 随包走**：包内含本版变更清单与回滚指引，运维看一眼就懂。

## 使用方式

1. 把待打包目录按 `sql/` `dist/` 命名约定组织（可改配置）。
2. 运行 `build_release_pkg.py`，传 version / sql_dir / dist_dir / output。
3. 脚本生成发布 zip（含 `MANIFEST.md` + 全部 SQL + 产物 + 自检清单），即可上线。

## 适用场景

会员中心、订单系统、内容平台等任意 Java/Spring Boot 后端；团队规范收口；新人一键上手；CI/CD 一条命令出包。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。