开源项目选型清单：别只看 Star 数

# ❌ 坏做法：人工检查 LICENSE 文件，容易遗漏
# 开发者 A 在 PR 里写了一句 "升级了 ES 到 8.x"
# reviewer 没注意许可证，直接 approve
 
# ✅ 好做法：在 CI 中集成许可证扫描
# .github/workflows/license-check.yml
name: License Compliance Check
on: [pull_request]
jobs:
  license-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check dependency licenses
        uses: fossa-contrib/fossa-action@v3
        with:
          fossa-api-key: ${{ secrets.FOSSA_API_KEY }}
          # 阻断含有 GPL/AGPL/SSPL 的依赖进入主分支
          fail-on-licenses: "GPL-2.0,GPL-3.0,AGPL-3.0,SSPL-1.0"

# ❌ 坏做法：只看 Star 数和下载量
# npm info some-date-lib stars
# → 12000 ⭐ → 感觉没问题
 
# ✅ 好做法：用脚本检查维护健康度
#!/bin/bash
REPO="author/some-date-lib"
 
# 1. 最近 90 天是否有 commit
LAST_COMMIT=$(gh api "/repos/$REPO/commits?per_page=1" \
  --jq '.[0].commit.committer.date')
echo "最后一次提交: $LAST_COMMIT"
 
# 2. 核心维护者数量（过去 6 个月提交超过 5 次的独立作者）
MAINTAINERS=$(gh api "/repos/$REPO/commits?since=2025-12-01" \
  --jq '[.[].author.login] | unique | length')
echo "近 6 个月活跃维护者: $MAINTAINERS 人"
 
# 3. Issue 平均响应时间
echo "请手动检查: gh issue list --repo $REPO --state closed"
 
# 判定标准：
# - 最近 commit 超过 90 天 → 风险
# - 活跃维护者 < 2 人 → 风险

# ❌ 坏做法：直接使用默认配置部署
# 只改了端口和数据库连接，其他全部保持默认
 
api-gateway:
  port: 8080
  database:
    host: db.internal
  # 其他配置全部省略，使用默认值
  # 默认开启了 debug endpoint
  # 默认日志级别 = DEBUG，会打印请求体
  # 默认没有限流配置
 
# ✅ 好做法：生产配置显式声明所有安全项
api-gateway:
  port: 8080
  database:
    host: db.internal
  # 安全配置必须显式声明，不依赖默认值
  debug:
    enabled: false              # 生产环境关闭调试接口
  logging:
    level: WARN                 # 不记录请求体
    redact-fields:              # 即使开 DEBUG 也脱敏
      - "authorization"
      - "cookie"
      - "x-api-key"
  rate-limit:
    enabled: true
    max-requests: 1000          # 单 IP 每分钟上限
    window: 60s
  cors:
    allowed-origins:            # 不使用默认的 *
      - "https://app.example.com"

<!-- ❌ 坏做法：口头决定，无记录 -->
<!-- 团队群聊里有人说 "用 fastify 吧，挺快的" -->
<!-- 三个月后没人记得为什么选了它 -->
 
<!-- ✅ 好做法：结构化 ADR（Architecture Decision Record） -->
# ADR-042: HTTP 框架选型
 
## 状态
已接受 - 2026-06-20
 
## 背景
需要替换 Express，原因是 TypeScript 支持差、中间件生态碎片化。
 
## 候选
| 维度       | Fastify     | Hono        | Koa         |
|-----------|-------------|-------------|-------------|
| 性能       | 高          | 极高        | 中          |
| TS 支持    | 原生         | 原生         | 需 @types   |
| 插件生态   | 丰富         | 中等         | 较少         |
| 维护者数量 | 8 人         | 3 人         | 1 人（不活跃） |
| 许可证     | MIT          | MIT          | MIT          |
 
## 决定
选择 Fastify。理由：TS 原生支持 + 插件生态丰富 + 维护团队稳定。
Hono 性能更好但插件生态不够成熟，作为备选。
 
## 风险
- Fastify 插件封装模式有学习成本
- 需要在 pino 日志集成上做适配
 
## 退出策略
如果 Fastify 维护停滞，可迁移到 Hono（两者路由 API 相似）。

// ❌ 坏做法：使用宽泛的版本范围
{
  "dependencies": {
    "some-lib": "*",        // 任意版本，随时可能 breaking
    "another-lib": ">=1.0"  // 可能拉到未测试的大版本
  }
}
 
// ✅ 好做法：锁定精确版本 + 定期升级
{
  "dependencies": {
    "some-lib": "3.2.1",         // 精确版本
    "another-lib": "2.0.4"       // 精确版本
  },
  "overrides": {
    // 强制子依赖使用安全版本
    "some-lib>transitive-dep": "1.5.0"
  }
}
// 配合 renovate / dependabot 定期自动升级
// 配合 npm audit 检查已知漏洞

# ❌ 坏做法：只看 README 里的介绍和 Star 数
# "This project is actively maintained!" → 这种话不能信
 
# ✅ 好做法：用数据验证活跃度
REPO="fastify/fastify"
 
# 最近 30 天 commit 数
echo "近 30 天 commit 数:"
gh api "/repos/$REPO/commits?since=$(date -d '30 days ago' +%Y-%m-%d)" \
  --jq 'length'
 
# 最近 30 天 PR 合并数
echo "近 30 天合并 PR 数:"
gh pr list --repo $REPO --state merged --search "merged:>=30 days ago" \
  --json number --jq 'length'
 
# 开放 issue 数量和平均标签
echo "开放 issue 数:"
gh issue list --repo $REPO --state open --json number --jq 'length'
 
# 核心贡献者（近 6 个月 commit > 10 次）
echo "核心贡献者:"
gh api "/repos/$REPO/commits?since=$(date -d '6 months ago' +%Y-%m-%d)" \
  --jq '[.[].author.login] | group_by(.) | map(select(length > 10)) | length'

// ❌ 坏做法：在业务代码中直接深度耦合第三方库 API
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
 
// 所有业务代码直接使用 AWS SDK 的类型和方法
async function uploadAvatar(userId: string, buffer: Buffer) {
  const client = new S3Client({ region: 'us-east-1' })
  await client.send(new PutObjectCommand({
    Bucket: 'avatars',
    Key: `${userId}.png`,
    Body: buffer,
  }))
}
 
// 如果要切换到 MinIO / R2 / 阿里云 OSS，需要改所有调用点
 
// ✅ 好做法：用抽象层隔离第三方依赖
interface FileStorage {
  upload(key: string, data: Buffer): Promise<string>
  download(key: string): Promise<Buffer>
  delete(key: string): Promise<void>
}
 
// AWS S3 实现
class S3FileStorage implements FileStorage {
  private client: S3Client
  constructor(private bucket: string, region: string) {
    this.client = new S3Client({ region })
  }
  async upload(key: string, data: Buffer) {
    await this.client.send(new PutObjectCommand({
      Bucket: this.bucket, Key: key, Body: data
    }))
    return `s3://${this.bucket}/${key}`
  }
  // download / delete 实现...
  async download(_key: string): Promise<Buffer> { throw new Error('TODO') }
  async delete(_key: string): Promise<void> { throw new Error('TODO') }
}
 
// MinIO 实现（迁移时只需新增实现，不改业务代码）
class MinIOFileStorage implements FileStorage {
  // 类似实现，API 差异在内部消化
  async upload(_key: string, _data: Buffer): Promise<string> { throw new Error('TODO') }
  async download(_key: string): Promise<Buffer> { throw new Error('TODO') }
  async delete(_key: string): Promise<void> { throw new Error('TODO') }
}
 
// 业务代码只依赖接口
async function uploadAvatar(storage: FileStorage, userId: string, buffer: Buffer) {
  const url = await storage.upload(`avatars/${userId}.png`, buffer)
  return url
}