|
4 | 4 |
|
5 | 5 | `码出高效,码出质量。` |
6 | 6 |
|
| 7 | +--- |
| 8 | +   |
7 | 9 | --- |
8 | 10 |
|
9 | 11 | ## 一、为什么需要这个 Skill |
|
22 | 24 |
|
23 | 25 | - 📚 **完整收录**黄山版 7 大维度(编程规约 / 异常日志 / 单元测试 / 安全规约 / MySQL / 工程结构 / 设计规约)共 2000+ 行条文 |
24 | 26 | - 🧭 **按需路由**——`SKILL.md` 只做导航,命中场景时才读取对应 `data/*.md`,节省 token |
| 27 | +- 🎯 **触发词精准定位**——18 条精确关键词映射,AI 无需推理即可直达对应章节 |
25 | 28 | - 🏷️ **保留分级**——每条规约标注【强制】/【推荐】/【参考】,AI 能区分优先级 |
26 | 29 | - ✅ **正例 + 反例**——条文附带提倡写法与真实故障雷区,AI 修复时有的放矢 |
| 30 | +- ⚖️ **冲突解决策略**——安全优先 > 强制优先 > 业务豁免 > 渐进改进,规约冲突时有据可依 |
| 31 | +- 👁️ **视角区分**——编写视角(即时决策)与审查视角(全局判断)分流,按任务类型推荐阅读路径 |
| 32 | +- 🎛️ **个性化配置**——通过 `memory.md` 覆盖手册规约或补充团队自有规范 |
27 | 33 |
|
28 | 34 | ## 二、规约来源 |
29 | 35 |
|
|
34 | 40 |
|
35 | 41 | 黄山版是阿里 Java 开发手册的最新公开版本,在其前身(嵩山版、泰山版等)基础上修订而成,是**中文 Java 社区影响力最大、被广泛采纳的工程规约**之一。手册以 Java 开发者视角划分为七个维度,并附三张参考表(版本历史、专有名词解释、错误码全量列表)。 |
36 | 42 |
|
37 | | -> ⚠️ **版权说明**:手册原文版权归阿里巴巴所有。本项目仅以 Skill 形式做工程化封装与便捷分发,便于开发者团队在 AI 辅助编码中统一遵循。如需官方原版,请参考阿里巴巴官方发布渠道。 |
| 43 | +> ⚠️ **版权说明**:手册原文版权归阿里巴巴所有。本项目仅以 Skill 形式做工程化封装与便捷分发,便于开发者团队在 AI 辅助编码中统一遵循。 |
38 | 44 |
|
39 | 45 | ## 三、仓库结构 |
40 | 46 |
|
41 | 47 | ``` |
42 | 48 | alibaba-java-development-guide/ |
43 | | -├── SKILL.md # 路由入口(AI 据此按需检索) |
| 49 | +├── SKILL.md # 路由入口 + 增强导航(触发词映射/冲突策略/视角区分/场景推荐) |
| 50 | +├── memory.md # 个人编码偏好配置(跨项目) |
44 | 51 | ├── README.md # 本文件 |
| 52 | +├── project/ |
| 53 | +│ ├── README.md # project/ 使用说明 |
| 54 | +│ ├── _template.md # 新建项目规范模板 |
| 55 | +│ └── <项目名>.md # 按项目名隔离的规范文件 |
45 | 56 | └── data/ |
46 | 57 | ├── 01-coding-standards.md # 一、编程规约(命名/OOP/集合/并发/注释...) |
47 | 58 | ├── 02-exception-logging.md # 二、异常日志(错误码/try-catch/NPE/日志) |
|
163 | 174 | | "Service 抛异常该怎么处理" | `02-exception-logging.md`(错误码、try-catch) | |
164 | 175 | | "DTO 和 VO 怎么分层" | `06-project-structure.md`(应用分层) | |
165 | 176 | | "帮我写这个方法的单测" | `03-unit-testing.md`(AIR、BCDE、Mock) | |
| 177 | +| "金额字段要不要用 BigDecimal" | 触发 `memory.md` + `01-coding-standards.md`(优先读团队偏好覆盖) | |
| 178 | +| "这个 JWT Token 设计安全吗" | 触发词 `JWT/Token` → `04-security-standards.md` | |
| 179 | +| "方法超 80 行了但单一职责拆不动" | 触发 `SKILL.md` 冲突策略 → 安全豁免 + 加注释说明 | |
| 180 | + |
| 181 | +### 个性化配置 |
| 182 | + |
| 183 | +本 skill 提供两层个性化配置,按优先级合并生效: |
| 184 | + |
| 185 | +``` |
| 186 | +memory.md (个人偏好)→ project/<项目名>.md (项目规范)→ 手册原文(基线) |
| 187 | +``` |
| 188 | + |
| 189 | +- **`memory.md`** — 你的个人编码习惯(金额类型、Lombok 偏好等),跨项目通用 |
| 190 | +- **`project/<项目名>.md`** — 项目团队规范(技术栈、命名约定、规约覆盖等),按项目隔离 |
| 191 | + |
| 192 | +**初始化**:首次使用时 AI 自动扫描项目 + 提问,生成对应文件 |
| 193 | +**持续更新**:日常编码中 AI 发现新规范时询问是否加入 |
166 | 194 |
|
167 | 195 | ## 七、许可证与贡献 |
168 | 196 |
|
|
0 commit comments