后端开发Skill backend-development

---

名称：后端开发 描述：后端API设计、数据库架构、微服务模式和测试驱动开发。用于设计API、数据库模式或后端系统架构。 来源：wshobson/agents 许可证：MIT

后端开发

API设计

RESTful 约定

GET    /users          # 列出用户
POST   /users          # 创建用户
GET    /users/:id      # 获取用户
PUT    /users/:id      # 更新用户（完整）
PATCH  /users/:id      # 更新用户（部分）
DELETE /users/:id      # 删除用户

GET    /users/:id/posts  # 列出用户的帖子
POST   /users/:id/posts  # 为用户创建帖子

响应格式

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

错误格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "无效输入",
    "details": [
      { "field": "email", "message": "无效格式" }
    ]
  }
}

数据库模式

模式设计

-- 使用UUID作为公共ID
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  public_id UUID DEFAULT gen_random_uuid() UNIQUE,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 软删除
ALTER TABLE users ADD COLUMN deleted_at TIMESTAMPTZ;

-- 索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_created ON users(created_at DESC);

查询模式

-- 使用游标分页
SELECT * FROM posts
WHERE created_at < $cursor
ORDER BY created_at DESC
LIMIT 20;

-- 高效计数
SELECT reltuples::bigint AS estimate
FROM pg_class WHERE relname = 'users';

认证

JWT 模式

interface TokenPayload {
  sub: string;      // 用户ID
  iat: number;      // 颁发时间
  exp: number;      // 过期时间
  scope: string[];  // 权限
}

function verifyToken(token: string): TokenPayload {
  return jwt.verify(token, SECRET) as TokenPayload;
}

中间件

async function authenticate(req: Request, res: Response, next: Next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    return res.status(401).json({ error: '未授权' });
  }

  try {
    req.user = verifyToken(token);
    next();
  } catch {
    res.status(401).json({ error: '无效令牌' });
  }
}

缓存策略

// 缓存旁路模式
async function getUser(id: string): Promise<User> {
  const cached = await redis.get(`user:${id}`);
  if (cached) return JSON.parse(cached);

  const user = await db.users.findById(id);
  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
  return user;
}

// 缓存失效
async function updateUser(id: string, data: Partial<User>) {
  await db.users.update(id, data);
  await redis.del(`user:${id}`);
}

限流

const limiter = rateLimit({
  windowMs: 60 * 1000,  // 1分钟
  max: 100,             // 每个窗口100个请求
  keyGenerator: (req) => req.ip,
  handler: (req, res) => {
    res.status(429).json({ error: '请求过多' });
  }
});

可观测性

• 日志记录：带有请求ID的结构化JSON日志
• 指标：请求延迟、错误率、队列深度
• 追踪：带有相关ID的分布式追踪
• 健康检查：/health 和 /ready 端点