react-node-practices

React & Node.js Best Practices

AI Agent 编写正确代码的知识包 - 灵感来自 Supabase Agent Skills

规则分类（按优先级）

优先级	类别	说明
🔴 Critical	安全 & 性能	必须遵守，违反将阻止提交
🟠 High	架构 & 模式	应该遵守，影响可维护性
🟡 Medium	代码质量	建议遵守，提升代码质量
🟢 Low	风格偏好	可选遵守，团队约定

---

🔴 Critical: 安全规则

SEC-001: 环境变量处理

// ❌ 错误：硬编码密钥
const apiKey = "sk-proj-xxxxx"
const dbUrl = "postgres://user:pass@localhost/db"

// ✅ 正确：环境变量
const apiKey = process.env.API_KEY
if (!apiKey) throw new Error('API_KEY not configured')

// ✅ 正确：使用 zod 验证环境变量
import { z } from 'zod'
const envSchema = z.object({
  API_KEY: z.string().min(1),
  DATABASE_URL: z.string().url(),
})
const env = envSchema.parse(process.env)

SEC-002: 用户输入验证

// ❌ 错误：信任用户输入
app.post('/user', (req, res) => {
  db.query(`SELECT * FROM users WHERE id = ${req.body.id}`)
})

// ✅ 正确：参数化查询 + 验证
import { z } from 'zod'
const userIdSchema = z.string().uuid()

app.post('/user', (req, res) => {
  const id = userIdSchema.parse(req.body.id)
  db.query('SELECT * FROM users WHERE id = $1', [id])
})

SEC-003: 敏感数据不入日志

// ❌ 错误：记录敏感信息
console.log('User login:', { email, password, token })
logger.info('Payment:', { cardNumber, cvv })

// ✅ 正确：脱敏处理
console.log('User login:', { email, password: '[REDACTED]' })
logger.info('Payment:', { cardLast4: card.slice(-4) })

SEC-004: XSS 防护

// ❌ 错误：直接渲染用户内容
<div dangerouslySetInnerHTML={{ __html: userContent }} />

// ✅ 正确：使用 DOMPurify 或避免 dangerouslySetInnerHTML
import DOMPurify from 'dompurify'
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />

// ✅ 更好：直接渲染文本
<div>{userContent}</div>

---

🔴 Critical: 性能规则

PERF-001: 避免 useEffect 瀑布

// ❌ 错误：串行请求
useEffect(() => {
  fetchUser().then(user => {
    fetchPosts(user.id).then(posts => {
      fetchComments(posts[0].id)
    })
  })
}, [])

// ✅ 正确：并行请求
useEffect(() => {
  Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchComments()
  ]).then(([user, posts, comments]) => {
    // 处理数据
  })
}, [])

// ✅ 更好：使用 React Query / SWR
const { data: user } = useQuery('user', fetchUser)
const { data: posts } = useQuery(['posts', user?.id], () => fetchPosts(user.id), {
  enabled: !!user
})