# 基础代码规范 `[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"
  }
}
```