---
name: java-coding-standards
description: 苍穹可用的 Java 语言层规范（命名/常量/格式/OOP/集合/控制/注释）。已剔除与金蝶平台冲突的框架示例。
---

# Java 语言层规范（无平台冲突）

仅语言与 JDK 习惯。**不含**日志门面、Spring、DAO/Service 分层、MyBatis、线程池工厂选型。  
插件生命周期、日志、查询、线程 → `ok-cosmic/rules/*` 与 `lang-vs-platform.md`。

## 1. 命名

- 禁止命名以下划线/`$` 开头或结尾
- 禁止拼音英文混用、中文标识符
- 类名 `UpperCamelCase`；方法/变量 `lowerCamelCase`
- 常量 `UPPER_SNAKE_CASE`，语义完整
- 抽象类 `Abstract`/`Base` 前缀；异常类 `Exception` 后缀；测试类 `*Test`
- 数组类型写法：`int[] arr`，勿 `String args[]`
- 包名全小写、单数语义；避免随意缩写
- 设计模式可体现在类名（`OrderFactory`、`LoginProxy`）
- 枚举类名 `*Enum`，成员全大写+下划线

**苍穹插件类名**（平台）：`*FormPlugin` / `*BillPlugin` / `*ListPlugin` / `*OpPlugin` 等，见 `platform-baseline`。勿套 Web 工程的 `*ServiceImpl`/`*DAO` 当插件模板。

## 2. 常量

- 禁止魔法值散落；长期不变值提为常量
- `long` 赋值用大写 `L`
- 浮点比较勿直接 `==`；金额用 `BigDecimal`，且避免 `new BigDecimal(double)`

## 3. 代码格式

- 大括号使用 K&R/阿里常见风格：`if (x) {` 同行开括号
- 单行字符数与缩进与**当前项目**一致，不强行改历史文件风格
- 运算符两侧空格；逗号后空格

## 4. OOP

- 覆写必须 `@Override`
- `equals`/`hashCode` 成对；注意 `Objects.equals`
- 慎用继承；组合优先
- 构造方法避免复杂业务与虚方法调用
- 序列化类注意 `serialVersionUID` 仅在确需序列化时

**不适用（已删除）**：强制 POJO 分层 DO/DTO/BO/VO、强制 Service/DAO 接口+Impl、MyBatis resultMap 布尔 `is_` 映射——苍穹主数据为 `DynamicObject`，以平台模型为准。

## 5. 集合

- 指定集合初始容量（可知大小时）
- `ArrayList#subList` 不可强转 `ArrayList`；视图与原列表联动
- `Arrays.asList` / 不可变集合勿 `add`/`remove`
- 遍历中勿直接修改集合结构；用迭代器或先收集再改
- `HashMap`/`ConcurrentHashMap` 空值语义差异需清楚
- 泛型勿使用原始类型

## 6. 并发（语言常识）

- 线程安全集合/锁的选用按场景
- `ThreadLocal` 用后清理，防泄漏
- **已删除**：`Executors` 工厂创建线程池、`new Thread` 业务用法示例  
  → Cosmic **必须** `kd.bos.threads.ThreadPools`（见平台规范）

## 7. 控制语句

- `switch` 每个 case 终止或明确 fall-through 注释
- 高复杂度分支优先卫语句
- 避免过深嵌套

## 8. 注释

- 类与公共方法应有意图说明；改代码同步改注释
- 禁止无意义注释（`// get user` 贴在 `getUser()` 上）
- TODO 须可跟进

## 9. 日期时间

- 优先 `java.time.*`；注意时区
- 格式化与解析用明确 pattern，勿依赖默认 locale 暗坑

## 明确不收录（与平台冲突，已删除）

| 已删除主题 | 原因 |
|------------|------|
| SLF4J / Log4j / JCL 用法 | 平台 `kd.bos.logging.Log` |
| Spring / `@Transactional` / DI | 插件非 Spring 应用 |
| Web/Service/Manager/DAO 分层 | 插件 + ServiceHelper |
| MyBatis / iBATIS / 手写 DO 映射 | DynamicObject + 平台查询 |
| MySQL 建表/索引长文 | PDM/设计器/KSQL 基线 |
| `System.out` / `printStackTrace` 正例 | 一律禁止 |
| HttpClient 框架样板 | 仅保留「远程必须超时」在平台规则 |

完整对照：[`../../rules/lang-vs-platform.md`](../../rules/lang-vs-platform.md)