Lyda
97 lines
2.1 KiB
Markdown
97 lines
2.1 KiB
Markdown
# 基础代码规范 `[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"
|
||
}
|
||
}
|
||
```
|