diff --git a/references/json.package.md b/references/json.package.md new file mode 100644 index 0000000..224fbd4 --- /dev/null +++ b/references/json.package.md @@ -0,0 +1,96 @@ +# 基础代码规范 `[Json.Package]` + +> - includes `package.json` `package-lock.json` `yarn.lock` `pnpm-lock.yaml` + +下面是 package.json 及 lock 文件的依赖管理规范 + +## 依赖变更需经评审 `[Json.Package.DependencyChangeReview]` + +> - severity `error` + +- 禁止随意添加、删除、修改依赖 +- 新增依赖需在 PR 描述中说明引入理由、使用场景及替代方案评估 +- 升级依赖大版本需经团队评审,评估 Breaking Changes 影响 +- 删除依赖前确认无其他模块引用 + +### Example: 依赖变更 + +#### Good: 有明确理由并评审通过 + +```json +// PR 描述中说明: +// 引入 lodash-es 用于高性能数组操作, +// 替代方案评估:手写工具函数可维护性差,同意引入 +{ + "dependencies": { + "lodash-es": "^4.17.21" + } +} +``` + +#### Bad: 随意添加未评审依赖 + +```json +// 无说明直接提交 +{ + "dependencies": { + "some-random-lib": "^1.0.0" + } +} +``` + +## lock 文件禁止手动修改 `[Json.Package.NoManualLockEdit]` + +> - severity `error` + +- 禁止直接手动编辑 lock 文件(package-lock.json / yarn.lock / pnpm-lock.yaml) +- lock 文件只能通过包管理器命令(npm/yarn/pnpm install/add/remove/update)自动生成 +- PR 中 lock 文件变更需与 package.json 变更对应,禁止出现不一致情况 + +### Example: lock 文件变更 + +#### Good: 通过命令自动生成 + +```bash +# 正确方式:使用包管理器命令 +pnpm add lodash-es +# 或 +pnpm remove unused-lib +``` + +#### Bad: 手动编辑 lock 文件 + +```yaml +# 手动修改 pnpm-lock.yaml 中的 checksum 或版本号 +``` + +## 依赖版本号使用 caret(^) 或波浪号(~) `[Json.Package.DependencyVersion]` + +- 生产依赖(dependencies)使用 `^` 允许小版本和补丁版本更新 +- 开发依赖(devDependencies)可使用 `~` 锁定小版本 +- 禁止锁定精确版本(无符号或 `=`),除非存在特殊兼容性要求 + +### Example: 版本号规范 + +#### Good: 使用 ^ 或 ~ + +```json +{ + "dependencies": { + "vue": "^3.3.0" + }, + "devDependencies": { + "eslint": "~8.50.0" + } +} +``` + +#### Bad: 锁定精确版本无说明 + +```json +{ + "dependencies": { + "vue": "3.3.4" + } +} +```