全栈开发宝典

DNS 解析 → TCP 握手 → TLS 握手 → 发送 HTTP 请求
  → CDN/网关（限流、鉴权、路由）
  → 应用进程（反序列化 → 参数校验 → 鉴权 → 业务编排）
  → 缓存查询（命中则返回）
  → 数据库查询（事务 / 锁 / 索引）
  → 渲染响应 → 网络回传 → 浏览器解析 → 首屏渲染 → 交互就绪

★ 每一步都可能成为瓶颈，定位时按序逐层排除，而不是猜测。

1. 现有方案是否已经无法解决？  （是 → 继续，否 → 停）
2. 问题能否用 20 行代码解决？  （能 → 自己写，不引依赖）
3. 引入的维护成本谁承担？      （无人承担 → 停）
4. 是否有降级/回滚方案？       （无 → 先设计方案）
5. 团队是否有 1 人以上真正熟悉？（无 → 先做技术验证 Spike）

★ 依赖的隐性成本 = 学习成本 + 升级成本 + 故障排查成本 + 安全补丁成本

/* —— 万能居中 —— */
.center { display:grid; place-items:center; }
.center-x { display:flex; justify-content:center; }
.holy { display:flex; align-items:center; justify-content:space-between; }

/* —— 经典后台骨架：头部 + 侧栏 + 内容 —— */
.layout{
  display:grid; height:100dvh;
  grid-template-columns:240px 1fr;
  grid-template-rows:56px 1fr;
  grid-template-areas:"header header" "side main";
}
.layout>header{grid-area:header} .layout>aside{grid-area:side;overflow:auto}
.layout>main{grid-area:main;overflow:auto}

/* —— 自适应卡片墙（不用媒体查询） —— */
.cards{display:grid;gap:16px;grid-template-columns:repeat(auto-fill,minmax(260px,1fr))}

/* —— 底部吸附：内容不足时 footer 仍在底部 —— */
.page{display:flex;flex-direction:column;min-height:100dvh}
.page>main{flex:1}

/* —— 单行省略 / 多行省略 —— */
.ell{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.ell-2{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}

/* —— 现代响应式：容器查询（按父容器而非视口） —— */
.wrap{container-type:inline-size}
@container (max-width:480px){ .card{grid-template-columns:1fr} }

/* —— 深浅色 —— */
:root{--bg:#fff;--fg:#111}
@media(prefers-color-scheme:dark){:root{--bg:#0b0e14;--fg:#dbe2ee}}

// 1) 判别联合：让非法状态无法构造
type Result<T> =
  | { ok:true; data:T }
  | { ok:false; code:'NOT_FOUND'|'FORBIDDEN'; msg:string };

function handle(r:Result<User>){
  if(r.ok){ console.log(r.data.name); }   // 此处 data 已收窄
  else   { console.log(r.code, r.msg); }
}

// 2) 泛型约束 + keyof：类型安全的取值
function pluck<T,K extends keyof T>(obj:T, keys:K[]):Pick<T,K>{
  return keys.reduce((a,k)=>(a[k]=obj[k],a), {} as Pick<T,K>);
}

// 3) 常用工具类型
// Partial 全部可选 | Required 全部必填 | Pick 挑字段 | Omit 排除字段
// Record<K,V> 映射 | ReturnType 取函数返回 | Awaited 解 Promise
// NonNullable 去空 | Exclude/Extract 联合运算
type UserDTO = Omit<User,'passwordHash'|'salt'> & { roleName:string };

// 4) satisfies：校验字面量结构但保留精确类型（比 as 安全）
const routes = {
  home:'/', login:'/login', user:'/u/:id'
} satisfies Record<string,string>;

// 5) 类型守卫：把 unknown 收窄成具体类型
function isUser(x:unknown):x is User{
  return typeof x==='object' && x!==null && 'id' in x && 'email' in x;
}

// 6) 模板字面量类型：约束字符串格式
type EventName = `on${Capitalize<'click'|'change'>}`;  // 'onClick'|'onChange'

// 7) 运行时校验：类型在编译后被擦除，边界处必须 zod 校验
import { z } from 'zod';
const CreateUser = z.object({
  email: z.string().email(),
  age:   z.number().int().min(0).max(150),
  role:  z.enum(['admin','user']).default('user'),
});
type CreateUserInput = z.infer<typeof CreateUser>;   // 类型由 schema 推导

// ✅ 声明式：状态变，UI 自动变
const [list,setList]=useState<User[]>([]);
const [q,setQ]=useState('');
// 派生数据直接算，不要额外存 state（避免状态不同步）
const filtered = useMemo(()=>list.filter(u=>u.name.includes(q)),[list,q]);

// ❌ 反模式：把派生数据放进 state + useEffect 同步
// const [filtered,setFiltered]=useState([]);
// useEffect(()=>setFiltered(list.filter(...)),[list,q]);  // 多一次渲染且易出 bug

// ✅ 请求数据的标准写法（含取消 + 竞态处理）
useEffect(()=>{
  const ac = new AbortController();
  setLoading(true);
  fetch(`/api/users?q=${q}`,{signal:ac.signal})
    .then(r=>r.json())
    .then(d=>setList(d.items))
    .catch(e=>{ if(e.name!=='AbortError') setError(e); })
    .finally(()=>setLoading(false));
  return ()=>ac.abort();     // 关键：清理，避免后发先至的响应覆盖
},[q]);

class ErrorBoundary extends React.Component<
  {fallback:React.ReactNode; children:React.ReactNode},
  {hasError:boolean}>
{
  state = { hasError:false };
  static getDerivedStateFromError(){ return { hasError:true }; }
  componentDidCatch(err:Error, info:React.ErrorInfo){
    reportError(err, info.componentStack);   // 上报 Sentry 等
  }
  render(){ return this.state.hasError ? this.props.fallback : this.props.children; }
}
// 用法：包在路由级或模块级，避免一个组件崩溃白屏整页

npx create-next-app@latest app --ts --app --tailwind --eslint --src-dir
# 目录约定
app/
  layout.tsx        # 根布局（必须含 html/body）
  page.tsx          # 路由页面
  loading.tsx       # 该段的 Suspense 兜底
  error.tsx         # 该段的错误边界（'use client'）
  not-found.tsx     # 404
  route.ts          # Route Handler（API）
  [id]/page.tsx     # 动态段
  (group)/          # 路由分组，不影响 URL
  @modal/           # 平行路由
middleware.ts       # 请求前拦截（鉴权/重写/国际化）

// Server Component（默认）：在服务端执行，可直接查库
export default async function Page({ searchParams }:{searchParams:{page?:string}}){
  const page = Number(searchParams.page ?? 1);
  const items = await db.post.findMany({ take:20, skip:(page-1)*20 });
  return <PostList items={items} />;
}

// 缓存策略（Next 14+）
export const revalidate = 60;                       // ISR：60 秒重新生成
export const dynamic = 'force-dynamic';             // 每次请求都渲染
const r = await fetch(url,{ next:{ revalidate:300, tags:['posts'] } });
revalidateTag('posts');                             // 写操作后主动失效

// Client Component：需要交互/浏览器 API 时加 'use client'
'use client';
export function Like({ id }:{id:string}){
  const [n,setN]=useState(0);
  return <button onClick={()=>setN(n+1)}>{n}</button>;
}

// Route Handler
export async function GET(req:Request){
  const { searchParams } = new URL(req.url);
  return Response.json({ ok:true, q:searchParams.get('q') });
}

// 防抖 + 节流的正确实现
export function debounce<T extends (...a:any[])=>void>(fn:T, wait=250){
  let t:ReturnType<typeof setTimeout>;
  return (...args:Parameters<T>)=>{ clearTimeout(t); t=setTimeout(()=>fn(...args),wait); };
}
export function throttle<T extends (...a:any[])=>void>(fn:T, wait=100){
  let last=0;
  return (...args:Parameters<T>)=>{
    const now=Date.now();
    if(now-last>=wait){ last=now; fn(...args); }
  };
}
// 长任务让出主线程
const yieldToMain = ()=>new Promise(r=>setTimeout(r,0));

Controller / Router   → 解析协议、参数校验、组装响应（不含业务规则）
    ↓
Service / UseCase     → 业务编排、事务边界、权限判定（不含 HTTP 概念）
    ↓
Repository / DAO      → 数据访问、SQL、缓存读写（不含业务规则）
    ↓
Infrastructure        → DB / Redis / MQ / 第三方 SDK

★ 铁律：上层可依赖下层，下层绝不反向依赖上层。
★ Service 层不出现 req/res 对象，否则无法被 CLI/队列/测试复用。
★ 跨层异常统一由最外层（全局异常过滤器）转换为 HTTP 响应。

// —— 统一成功/失败响应 ——
type Ok<T> = { code:0; data:T; traceId:string };
type Err    = { code:number; message:string; traceId:string };

// —— 业务异常（带 HTTP 语义但不依赖框架）——
export class BizError extends Error {
  constructor(public status:number, message:string, public code=status){
    super(message);
  }
}

// service/user.service.ts —— 纯业务，可单测
export class UserService {
  constructor(private repo:UserRepo, private mailer:Mailer){}
  async register(input:CreateUserInput){
    if(await this.repo.existsByEmail(input.email))
      throw new BizError(409,'邮箱已注册');
    const hash = await argon2.hash(input.password);   // 绝不明文存密码
    const user = await this.repo.create({...input, passwordHash:hash});
    await this.mailer.sendWelcome(user.email);        // 副作用放最后，失败不阻断主流程
    return sanitize(user);                            // 出参脱敏
  }
}

// —— 全局错误处理（Express 中间件）——
app.use((err:Error,req:Request,res:Response,next:NextFunction)=>{
  const traceId = req.traceId;
  if(err instanceof BizError){
    return res.status(err.status).json({code:err.code,message:err.message,traceId});
  }
  logger.error({err,traceId,url:req.url},'unhandled');
  res.status(500).json({code:500,message:'服务器内部错误',traceId});  // 不泄漏堆栈
});

const PageQuery = z.object({
  page:  z.coerce.number().int().min(1).max(10000).default(1),
  size:  z.coerce.number().int().min(1).max(100).default(20),   // 必须限制上限！
  sort:  z.enum(['createdAt','name']).default('createdAt'),
  order: z.enum(['asc','desc']).default('desc'),
});
app.get('/users', async (req,res)=>{
  const q = PageQuery.parse(req.query);          // 校验失败自动抛 400
  res.json(await userService.list(q));
});

app.post('/orders', async (req,res,next)=>{
  const key = req.header('Idempotency-Key');
  if(!key) return res.status(400).json({message:'缺少 Idempotency-Key'});
  const cacheKey = `idem:${req.userId}:${key}`;
  const cached = await redis.get(cacheKey);
  if(cached) return res.json(JSON.parse(cached));       // 重复请求：直接回放
  const result = await orderService.create(req.userId, req.body);
  await redis.set(cacheKey, JSON.stringify(result), 'EX', 86400);
  res.status(201).json(result);
});

// 密码存储：argon2id > bcrypt(cost 12) > scrypt。禁止 MD5/SHA1/裸 SHA256
import argon2 from 'argon2';
const hash = await argon2.hash(pwd, { type:argon2.argon2id });
const ok   = await argon2.verify(hash, pwd);

// JWT 签发：只放必要声明，别塞敏感信息（payload 仅 base64，可解码）
const access = jwt.sign({ sub:user.id, role:user.role, tv:user.tokenVersion },
                        process.env.JWT_SECRET!, { expiresIn:'15m' });

// 鉴权中间件（RBAC）
function requireRole(...roles:Role[]){
  return (req,res,next)=>{
    if(!req.user) return res.status(401).end();
    if(!roles.includes(req.user.role)) return res.status(403).end();
    next();
  };
}
app.delete('/admin/users/:id', requireRole('admin'), handler);

// ★ 越权防护：查询必须带上归属条件，不能只查 id
await db.post.deleteMany({ where:{ id, authorId:req.user.id } });  // ✅ 而非 delete({where:{id}})

const emailQ = new Queue('email',{ connection:redis });

// 生产者
await emailQ.add('welcome', { userId }, {
  attempts:3,                                    // 重试次数
  backoff:{ type:'exponential', delay:2000 },    // 指数退避
  removeOnComplete:{ count:1000 },
  removeOnFail:{ age:7*86400 },
});

// 消费者（独立进程）
new Worker('email', async job=>{
  if(job.name==='welcome') await mailer.sendWelcome(job.data.userId);
}, { connection:redis, concurrency:10,
     limiter:{ max:100, duration:60_000 } });    // 限流保护下游

// 定时任务（也可用 cron / 数据库锁保证单实例）
await emailQ.upsertJobScheduler('digest', { pattern:'0 9 * * *' }, { name:'digest' });

res.writeHead(200,{
  'Content-Type':'text/event-stream',
  'Cache-Control':'no-cache, no-transform',
  'Connection':'keep-alive',
  'X-Accel-Buffering':'no',        // 关键：禁止 Nginx 缓冲
});
for await (const chunk of stream){
  res.write(`data: ${JSON.stringify(chunk)}\n\n`);
}
res.write('event: done\ndata: {}\n\n'); res.end();

// ① 超时（默认无超时 = 连接泄漏）② 重试（仅幂等 + 仅网络/5xx）
// ③ 熔断（连续失败快速失败）④ 降级（返回兜底数据）
const api = axios.create({ baseURL, timeout:3000 });        // 连接+读取超时

async function callWithRetry<T>(fn:()=>Promise<T>, n=3):Promise<T>{
  let lastErr;
  for(let i=0;i<n;i++){
    try{ return await fn(); }
    catch(e){
      lastErr = e;
      const retryable = !e.response || e.response.status >= 500;  // 4xx 不重试
      if(!retryable || i===n-1) break;
      await sleep(2**i * 300 + Math.random()*200);   // 指数退避 + 抖动防惊群
    }
  }
  throw lastErr;
}

CREATE TABLE users (
  id          BIGSERIAL PRIMARY KEY,
  email       VARCHAR(255) NOT NULL,
  password_hash TEXT       NOT NULL,
  role        SMALLINT     NOT NULL DEFAULT 0,
  created_at  TIMESTAMPTZ  NOT NULL DEFAULT now(),
  updated_at  TIMESTAMPTZ  NOT NULL DEFAULT now(),
  deleted_at  TIMESTAMPTZ
);

-- 软删除下保证未删除记录唯一（Pg 部分索引）
CREATE UNIQUE INDEX uk_users_email ON users(email) WHERE deleted_at IS NULL;

-- 常用组合查询索引：注意「区分度高的列放前面」
CREATE INDEX idx_users_role_created ON users(role, created_at DESC);

COMMENT ON COLUMN users.role IS '0=member,1=admin,2=superadmin';

-- 索引 (a, b, c) 能加速：
WHERE a=1                         ✅
WHERE a=1 AND b=2                 ✅
WHERE a=1 AND b=2 AND c=3         ✅
WHERE a=1 ORDER BY b              ✅
WHERE b=2                         ❌ 未用最左列
WHERE a=1 AND c=3                 ⚠️ 只用到 a，c 部分无法定位
WHERE a>1 AND b=2                 ⚠️ 范围列之后的列无法再用索引定位

-- 覆盖索引：查询列全在索引里，无需回表 → Using index
CREATE INDEX idx_cover ON orders(user_id, status) INCLUDE (amount);

-- 函数/表达式索引：别在列上包函数（会导致索引失效）
WHERE lower(email)='a@b.com'      ❌
CREATE INDEX idx_lower_email ON users(lower(email));   ✅ 建表达式索引

-- 隐式转换陷阱：字符串列传数字、不同字符集/排序规则 JOIN → 索引失效
-- LIKE 前缀匹配可用索引，'%xxx' 不可用（改用全文检索/倒排）

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM orders WHERE user_id=42 ORDER BY id DESC LIMIT 20;

-- MySQL 慢查询定位
SET GLOBAL slow_query_log='ON'; SET GLOBAL long_query_time=1;
SELECT * FROM sys.statement_analysis ORDER BY avg_latency DESC LIMIT 10;

-- Pg 慢查询：pg_stat_statements（必装扩展）
SELECT calls, round(mean_exec_time::numeric,2) ms, query
FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;

-- ❌ 深分页：OFFSET 100000 要扫描并丢弃 10 万行
SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 100000;

-- ✅ 游标分页（keyset）：利用索引直接定位
SELECT * FROM orders WHERE id < :last_id ORDER BY id DESC LIMIT 20;

-- ✅ 延迟关联：先查 ID 再回表，减少回表量
SELECT * FROM orders o JOIN
  (SELECT id FROM orders ORDER BY id LIMIT 20 OFFSET 100000) t USING(id);

-- 悲观锁：先锁后改，适合高冲突（库存、余额）
BEGIN;
SELECT * FROM sku WHERE id=1 FOR UPDATE;      -- 行锁（必须走索引，否则锁表！）
UPDATE sku SET stock=stock-1 WHERE id=1 AND stock>=1;
COMMIT;

-- 乐观锁：版本号，适合低冲突（大多数业务）
UPDATE sku SET stock=stock-1, version=version+1
WHERE id=1 AND version=:expected_version;
-- 影响行数 0 → 说明被并发修改，重试或报错

-- 原子 upsert（避免「先查再插」的竞态）
INSERT INTO user_login(user_id, date, times) VALUES (1, CURRENT_DATE, 1)
ON CONFLICT (user_id, date) DO UPDATE SET times = user_login.times + 1;

-- 防死锁：固定加锁顺序（如都按 id 升序）、缩短事务、避免事务内做远程调用

// ❌ N+1：每篇都查一次作者
const posts = await db.post.findMany();
for(const p of posts) p.author = await db.user.findUnique({where:{id:p.authorId}});

// ✅ include 一次性 join / 或 dataloader 批处理
const posts = await db.post.findMany({
  select:{ id:true, title:true, author:{ select:{ id:true, name:true } } },
  take:20, skip:(page-1)*20,
  orderBy:{ createdAt:'desc' },
});
const [items, total] = await db.$transaction([
  db.post.findMany({...}), db.post.count({where}),
]);

// 事务（隔离级别 + 超时）
await db.$transaction(async (tx)=>{
  await tx.order.create({data});
  await tx.sku.update({where:{id}, data:{stock:{decrement:1}}});
}, { isolationLevel:'ReadCommitted', timeout:5000 });

// Cache-Aside 标准读路径（最常用）
async function getOrLoad<T>(key:string, ttl:number, load:()=>Promise<T>):Promise<T>{
  const hit = await redis.get(key);
  if(hit) return JSON.parse(hit);

  // 单飞锁：同一 key 只有一个请求去回源，其余短暂等待
  const lockKey = `lock:${key}`;
  const got = await redis.set(lockKey,'1','EX',10,'NX');
  if(!got){ await sleep(50); return getOrLoad(key,ttl,load); }   // 递归等一等

  try{
    const data = await load();
    const val = data === null ? '__NULL__' : JSON.stringify(data);
    await redis.set(key, val, 'EX', ttl + Math.floor(Math.random()*ttl*0.2)); // 抖动防雪崩
    return data;
  } finally { await redis.del(lockKey); }
}

// 写路径：先更新 DB，再删除缓存（不是更新缓存！）
await db.user.update(...);  await redis.del(`user:${id}`);
// 高一致要求：延迟双删（删 → 等 500ms → 再删）或订阅 binlog（Canal/Debezium）异步失效

// 分布式锁（Redlock 简化版，务必设置自动过期 + 校验随机值再删）
const val = crypto.randomUUID();
const ok = await redis.set(lockKey, val, 'EX', 30, 'NX');
// 释放时用 Lua 保证「判断 + 删除」原子性：
// if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) else return 0 end

main          ← 永远可部署，保护分支，禁止直推
 └ feature/xxx  ← 从 main 切出，PR 合并后删除
 └ fix/xxx
 └ release/v1.2 ← 需要并行维护多版本时才引入（Git Flow）

流程：切分支 → 小步提交 → 提 PR（需 1 人 Review + CI 全绿）→ Squash Merge → 删分支

<type>(<scope>): <subject>
feat(user): 新增手机号登录
fix(order): 修复优惠券重复核销
perf(db): 订单列表深分页改游标分页
refactor(auth): 抽离权限校验中间件
docs(api): 补充分页参数说明
test(pay): 增加退款幂等用例
chore(deps): 升级 vite 到 5.4
revert: 回滚 feat(user): xxx

★ type: feat|fix|perf|refactor|docs|test|build|ci|chore|revert
★ 好处：自动生成 CHANGELOG、语义化版本号、一眼看懂改动意图

# 把当前分支的提交整理干净后再合入（个人分支用，公共分支禁用）
git rebase -i HEAD~3                 # squash / reword / drop
git rebase main                      # 同步主干，避免「合并提交」污染历史

# 只把某次提交挪过来（线上热修常用）
git cherry-pick <commit>

# 撤销已 push 的错误提交（保留历史，安全）
git revert <commit>

# 手滑切走了分支，找回丢失的提交
git reflog  →  git checkout <hash>

# 临时保存工作区
git stash push -m "wip"  /  git stash pop

# 提交前自检：只看本次改动的 diff
git diff --staged

      /E2E\        10%  关键业务链路（登录→下单→支付），慢但覆盖真实链路
     /------\
    / 集成测试 \    30%  API + DB + 缓存，最有性价比
   /------------\
  /   单元测试    \  60%  纯函数、业务规则，快（毫秒级）、无外部依赖
 /----------------\

★ 经验：不要追求覆盖率数字，追求「改动后敢不敢发版」。
★ 有价值的测试：覆盖 bug 复现路径、边界条件、金额/权限/幂等等易错逻辑。

describe('UserService.register', ()=>{
  it('邮箱重复时抛 409', async ()=>{
    const repo = { existsByEmail: vi.fn().mockResolvedValue(true),
                   create: vi.fn() } as unknown as UserRepo;
    await expect(new UserService(repo, mailer).register(input))
      .rejects.toMatchObject({ status:409 });
    expect(repo.create).not.toHaveBeenCalled();     // 断言副作用未发生
  });
});

// 集成测试：起真实 DB（Testcontainers）或独立 test schema，跑事务回滚
beforeEach(async ()=>{ await db.$executeRaw`BEGIN`; });
afterEach (async ()=>{ await db.$executeRaw`ROLLBACK`; });

// E2E（Playwright）：只测关键路径
test('下单流程', async ({page}) =>{
  await page.goto('/login');
  await page.fill('[name=email]', 'a@b.com');
  await page.click('button[type=submit]');
  await expect(page).toHaveURL('/');
});

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: pnpm }
      - run: corepack enable && pnpm install --frozen-lockfile
      - run: pnpm lint && pnpm typecheck
      - run: pnpm test --coverage
      - run: pnpm build
      - uses: docker/build-push-action@v6       # 仅 main 分支推送镜像
        if: github.ref == 'refs/heads/main'
        with: { push: true, tags: ghcr.io/org/app:${{ github.sha }} }

# —— 多阶段构建：产物镜像不含 devDependencies 与源码工具 ——
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm build && pnpm prune --prod      # 构建完再裁掉开发依赖

FROM node:22-alpine AS run
WORKDIR /app
ENV NODE_ENV=production
# ★ 用非 root 用户运行
RUN addgroup -S app && adduser -S app -G app
COPY --from=build --chown=app:app /app/node_modules ./node_modules
COPY --from=build --chown=app:app /app/dist ./dist
USER app
EXPOSE 3000
# ★ 用 exec 形式 + init 处理信号，保证优雅退出
CMD ["node","dist/main.js"]

services:
  app:
    build: .
    ports: ["3000:3000"]
    env_file: .env
    depends_on:
      db:  { condition: service_healthy }
      rds: { condition: service_started }
    restart: unless-stopped
  db:
    image: postgres:16-alpine
    environment: { POSTGRES_PASSWORD: dev, POSTGRES_DB: app }
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL","pg_isready -U postgres"]
      interval: 5s  retries: 10
  rds:
    image: redis:7-alpine
    command: ["redis-server","--maxmemory","256mb","--maxmemory-policy","allkeys-lru"]
volumes: { pgdata: {} }

# .env.example 提交到仓库（只有键，无值）；.env 加入 .gitignore
DATABASE_URL=postgres://user:pass@localhost:5432/app
REDIS_URL=redis://localhost:6379
JWT_SECRET=                 # 必填，启动时校验，缺失直接 fail-fast
LOG_LEVEL=info

# 启动时校验配置，避免运行到一半才发现缺配置
const env = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET:   z.string().min(32),
  PORT:         z.coerce.number().default(3000),
}).parse(process.env);        // 校验失败进程立即退出并打印缺哪个变量

import pino from 'pino';
export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  redact: ['req.headers.authorization','password','idCard'],   // 自动脱敏
  base: { service:'api', version:APP_VERSION },
});

// 每个请求注入 traceId（中间件）
const traceId = req.header('x-trace-id') ?? crypto.randomUUID();
const log = logger.child({ traceId, userId:req.user?.id });
req.log = log;   // 后续所有日志自动带上上下文

log.info({ rows:120, ms:35 }, 'query users');

// 1) SQL 注入 —— 绝不用模板字符串拼 SQL
await db.$queryRaw`SELECT * FROM users WHERE email = ${email}`;   // ✅ 参数化
// await db.$queryRawUnsafe(`... '${email}'`);                    // ❌ 注入之门

// 2) XSS —— 框架默认转义；危险场景用 DOMPurify
// ❌ dangerouslySetInnerHTML={{__html: userInput}}
// ✅ 富文本：服务端清洗 + 前端 DOMPurify.sanitize() + CSP

// 3) CSRF —— SameSite=Strict Cookie + 双重提交 Token（同源校验 Origin）
res.cookie('sid', id, { httpOnly:true, secure:true, sameSite:'strict', maxAge:7*86400000 });

// 4) 文件上传 —— 校验类型用「魔数」而非扩展名；重命名；存对象存储；禁止执行权限
if(!['image/jpeg','image/png'].includes(mimeFromBuffer))
  throw new BizError(400,'不支持的文件类型');

// 5) 敏感信息泄漏 —— 出参白名单，禁止直接吐 ORM 实体
const safe = (({id,name,email})=>({id,name,email}))(user);   // ✅ 显式挑字段

// 6) 安全响应头（Helmet 一句话搞定）
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'; frame-ancestors 'none'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin

// Redis 滑动窗口限流（Lua 保证原子性）
-- KEYS[1]=key  ARGV[1]=window(ms)  ARGV[2]=limit
redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, now - ARGV[1])
local cnt = redis.call('ZCARD', KEYS[1])
if cnt < tonumber(ARGV[2]) then
  redis.call('ZADD', KEYS[1], now, now .. '-' .. math.random())
  redis.call('PEXPIRE', KEYS[1], ARGV[1])
  return 1
end
return 0

// 分层限流：网关（全局 IP 级）→ 应用（用户/接口级）→ 下游（防打爆依赖）
// 登录/短信/支付接口单独配置更严格阈值（如 5 次/分钟 + 图形验证码）

// 领域事件：发布（在事务内写 outbox 表，保证不丢）
await db.$transaction(async tx=>{
  const order = await tx.order.create({data});
  await tx.outbox.create({ data:{
    topic:'order.paid',
    payload:{ orderId:order.id, amount:order.amount },
  }});
});
// 独立 Relay 进程轮询 outbox → 投递 MQ → 标记已发送（至少一次）

// 消费端必须幂等（消息会重复投递）
async function onOrderPaid(evt){
  const exists = await db.processedEvent.findUnique({where:{eventId:evt.id}});
  if(exists) return;                                  // 已处理过，直接返回
  await db.$transaction(async tx=>{
    await tx.processedEvent.create({data:{eventId:evt.id}});  // 去重表唯一索引
    await tx.inventory.deduct(evt.payload);
  });
}

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [ {duration:'1m',target:50}, {duration:'3m',target:50}, {duration:'1m',target:0} ],
  thresholds: { http_req_duration:['p95<500'], http_req_failed:['rate<0.01'] },
};
export default function(){
  const r = http.get('https://api.example.com/users',{headers:{Authorization:`Bearer ${TOKEN}`}});
  check(r, { 'status 200': (x)=>x.status===200 });
  sleep(1);
}
// k6 run --vus 50 --duration 5m script.js
// ★ 压测要渐增，观察拐点（QPS 不再涨而延迟飙升处即容量上限）

# 安装 uv（替代 pip/venv/pipx/poetry 的一体化工具，快 10~100 倍）
curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12          # 管理解释器版本
uv venv && source .venv/bin/activate
uv add fastapi uvicorn[standard] sqlalchemy asyncpg pydantic-settings
uv add --dev pytest ruff mypy httpx
uv lock && uv sync --frozen      # 锁文件 + CI 复现安装
uv run pytest                    # 自动在虚拟环境中执行

# 传统方式（pyproject.toml 同样适用）
python -m venv .venv && pip install -r requirements.txt
pip freeze > requirements.txt    # 建议改用 pip-compile / uv lock

app/
  main.py              # 应用入口、装配路由与中间件
  core/
    config.py          # pydantic-settings 读取环境变量（带校验）
    security.py        # 密码哈希、JWT
    deps.py            # 依赖注入：get_db / get_current_user
  api/v1/
    routers/user.py    # 路由（薄，只做参数与响应）
  domain/              # 业务规则（不依赖框架）
  models/              # SQLAlchemy ORM 模型
  schemas/             # Pydantic DTO（入参/出参）
  services/            # 业务编排
  repositories/        # 数据访问
tests/
alembic/               # 数据库迁移
pyproject.toml

from dataclasses import dataclass
from typing import Annotated, Literal, TypeAlias, Self
from pydantic import BaseModel, Field, EmailStr, field_validator

# 1) 现代类型写法（3.10+）：X | None 取代 Optional[X]
def find(uid: int) -> User | None: ...

# 2) 类型别名与字面量约束
Role: TypeAlias = Literal["admin", "user", "guest"]

# 3) Pydantic v2：运行时校验 + 自动文档（唯一可信的边界校验）
class CreateUserIn(BaseModel):
    model_config = {"extra": "forbid"}            # 拒绝未知字段，防字段误传
    email: EmailStr
    password: str = Field(min_length=8, max_length=72)   # bcrypt 上限 72 字节
    role: Role = "user"

    @field_validator("password")
    @classmethod
    def strong(cls, v: str) -> str:
        if v.isalpha(): raise ValueError("密码需包含数字")
        return v

class UserOut(BaseModel):
    model_config = {"from_attributes": True}      # 允许从 ORM 对象构造
    id: int
    email: EmailStr

# ★ 出参必须单独定义 schema，绝不直接返回 ORM 对象（会泄漏 password_hash）

# 4) 工具链配置（pyproject.toml 片段）
# [tool.ruff]  line-length = 100 ; select = ["E","F","I","UP","B","SIM"]
# [tool.mypy]  strict = true
# ruff check . && ruff format .   （替代 flake8+black+isort，快 100 倍）

from contextlib import asynccontextmanager
from fastapi import FastAPI, Depends, HTTPException, status, Query, Request
from sqlalchemy.ext.asyncio import AsyncSession

@asynccontextmanager
async def lifespan(app: FastAPI):
    await init_db()          # 启动时初始化连接池
    yield
    await engine.dispose()   # 关闭时优雅释放

app = FastAPI(lifespan=lifespan, title="API", version="1.0.0")

# —— 依赖注入：数据库连接按请求作用域自动开关 ——
async def get_db() -> AsyncIterator[AsyncSession]:
    async with SessionLocal() as s:
        try:
            yield s
            await s.commit()
        except Exception:
            await s.rollback(); raise

DbDep = Annotated[AsyncSession, Depends(get_db)]
CurrentUser = Annotated[User, Depends(get_current_user)]   # 鉴权依赖可复用

@app.post("/users", response_model=UserOut, status_code=status.HTTP_201_CREATED)
async def create_user(payload: CreateUserIn, db: DbDep):
    if await user_repo.exists_by_email(db, payload.email):
        raise HTTPException(409, "邮箱已注册")
    return await user_service.register(db, payload)

@app.get("/users", response_model=list[UserOut])
async def list_users(
    page: int = Query(1, ge=1), size: int = Query(20, ge=1, le=100), db: DbDep = None
): ...

# —— 全局异常处理：统一错误体 + traceId ——
@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    trace_id = request.headers.get("x-trace-id", uuid4().hex)
    logger.exception("unhandled", extra={"trace_id": trace_id})
    return JSONResponse(status_code=500,
                        content={"code": 500, "message": "服务器内部错误", "traceId": trace_id})

# ★ 关键性能规则：
# - def（同步）路由会自动跑线程池，async def 里绝不能调用阻塞 IO
# - async def 中调用 requests/time.sleep/同步 ORM = 阻塞整个事件循环，全站卡顿
# - 阻塞库要么改成 def 路由，要么用 run_in_executor / 换 httpx、asyncpg

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, selectinload
from sqlalchemy import select, func

class Base(DeclarativeBase): pass

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(unique=True, index=True)
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())

# 2.0 风格查询（不再是 Query API）
stmt = select(User).where(User.email == email).limit(1)
user = (await db.execute(stmt)).scalar_one_or_none()

# ★ N+1 治理：用 selectinload / joinedload 预加载
stmt = select(Post).options(selectinload(Post.author)).limit(20)   # ✅ 2 条 SQL
# for p in posts: p.author   ❌ 循环里触发 20 条查询

# 分页（游标优于 offset）
stmt = select(Post).where(Post.id < cursor).order_by(Post.id.desc()).limit(20)

# 事务：session 默认以 commit 结束；嵌套用 savepoint
async with db.begin():
    ...

# Alembic 迁移
# uv add alembic && alembic init alembic
# alembic revision --autogenerate -m "add users"   （必须人工审阅生成的脚本！）
# alembic upgrade head / downgrade -1

# 并发抓取：Semaphore 限制并发，防止打爆下游
async def fetch_all(urls: list[str]):
    sem = asyncio.Semaphore(10)
    async with httpx.AsyncClient(timeout=3.0) as client:
        async def one(u: str):
            async with sem:
                r = await client.get(u)
                r.raise_for_status()
                return r.json()
        return await asyncio.gather(*map(one, urls), return_exceptions=True)

# CPU 密集：交给进程池
loop = asyncio.get_running_loop()
result = await loop.run_in_executor(process_pool, heavy_compute, data)

# ★ GIL 真相：3.13 起可选 free-threading，但生态未就绪。
#   生产高并发仍以「多进程 + 异步 IO」为主：uvicorn --workers N

import pytest
from httpx import AsyncClient, ASGITransport

@pytest.fixture
async def client(db_session) -> AsyncClient:
    app.dependency_overrides[get_db] = lambda: db_session    # 替换依赖
    async with AsyncClient(transport=ASGITransport(app), base_url="http://t") as c:
        yield c
    app.dependency_overrides.clear()

@pytest.mark.parametrize("email,expect", [("a@b.com",201), ("bad",422), (None,422)])
async def test_create_user(client, email, expect):
    r = await client.post("/users", json={"email": email, "password": "Ab123456"})
    assert r.status_code == expect

# 每个用例独立事务并回滚，保证互相隔离
@pytest.fixture
async def db_session():
    async with engine.connect() as conn:
        ts = await conn.begin()
        yield AsyncSession(bind=conn)
        await ts.rollback()

# uv run pytest -q --cov=app --cov-report=term-missing

# 生产运行：gunicorn 管进程 + uvicorn worker 管协程
gunicorn app.main:app -k uvicorn.workers.UvicornWorker \
  --workers 4 --worker-connections 1000 --timeout 60 --graceful-timeout 30 --bind 0.0.0.0:8000
# workers 建议 = CPU 核数（IO 密集可 2*核+1），不要盲目加大

# Dockerfile（uv 多阶段）
FROM python:3.12-slim AS build
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable      # 依赖与源码分离，缓存友好
FROM python:3.12-slim
COPY --from=build --chown=app:app /app/.venv /app/.venv
COPY --chown=app:app ./app /app/app
USER app
ENV PATH="/app/.venv/bin:$PATH"
CMD ["gunicorn","app.main:app","-k","uvicorn.workers.UvicornWorker","--workers","4"]

com.example.app
 ├ common/          # 统一响应 R<T>、异常、工具、常量
 │   ├ Result.java  GlobalExceptionHandler.java
 ├ config/          # 配置类、拦截器、WebMvcConfigurer
 ├ security/        # 认证、鉴权、JWT 过滤器
 └ modules/
    └ order/        # ★ 按域聚合，而不是全局 controller/service/mapper 平铺
       ├ OrderController.java
       ├ OrderService.java / OrderServiceImpl.java
       ├ OrderMapper.java
       ├ entity/Order.java          # 与表对应（PO）
       ├ dto/OrderCreateReq.java OrderVO.java
       └ convert/OrderConvert.java  # MapStruct 接口

// 1) record：不可变 DTO，一行替代 getter/equals/hashCode/toString
public record UserVO(Long id, String email, String roleName) {}

// 2) 密封接口：限定实现范围，配合 switch 模式匹配可穷尽分支
public sealed interface PayResult permits Success, Failed, Pending {}

// 3) 模式匹配 + switch 表达式
String desc = switch (result) {
    case Success s  -> "成功 " + s.txnId();
    case Failed f   -> "失败 " + f.reason();
    case Pending p  -> "处理中";
};   // 密封接口无需 default，编译期保证穷尽

// 4) Optional 的正确用法：只用于「返回值」，不要做参数/字段
public Optional<User> findByEmail(String email) { ... }
findByEmail(e).map(User::getName).orElse("匿名");        // ✅
// Optional.ofNullable(x).get()  ❌ 不如直接判空

// 5) 文本块（SQL/JSON 可读性救星）
String sql = """
    SELECT id, email FROM users
    WHERE created_at >= ? AND status = ?
    """;

// 6) 异常：受检异常用于「调用方必须处理」，业务异常用自定义 RuntimeException
public class BizException extends RuntimeException {
    private final int code;
    public BizException(int code, String msg){ super(msg); this.code = code; }
}

@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor          // 构造器注入（优于 @Autowired 字段注入，便于测试）
public class OrderController {
    private final OrderService orderService;

    @PostMapping
    public Result<OrderVO> create(@Valid @RequestBody OrderCreateReq req) {
        return Result.ok(orderService.create(req));
    }

    @GetMapping
    public Result<PageResult<OrderVO>> page(
            @RequestParam(defaultValue = "1") @Min(1) int page,
            @RequestParam(defaultValue = "20") @Max(100) int size) {
        return Result.ok(orderService.page(page, size));
    }
}

// 入参校验
public record OrderCreateReq(
    @NotNull Long skuId,
    @NotNull @Min(1) @Max(9999) Integer quantity,
    @NotBlank @Size(max = 200) String remark) {}

// 统一响应 + 全局异常处理
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> onValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
            .map(f -> f.getField() + ":" + f.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return Result.fail(400, msg);
    }
    @ExceptionHandler(BizException.class)
    public Result<Void> onBiz(BizException e) { return Result.fail(e.getCode(), e.getMessage()); }
    @ExceptionHandler(Exception.class)
    public Result<Void> onErr(Exception e, HttpServletRequest req) {
        String traceId = MDC.get("traceId");
        log.error("unhandled uri={} traceId={}", req.getRequestURI(), traceId, e);
        return Result.fail(500, "服务器内部错误");     // 不暴露堆栈
    }
}

@Service
@RequiredArgsConstructor
public class OrderServiceImpl implements OrderService {
    private final OrderMapper mapper;
    private final InventoryClient inventory;

    @Transactional(rollbackFor = Exception.class, timeout = 5)   // 明确回滚范围 + 超时
    public OrderVO create(OrderCreateReq req) {
        if (mapper.existsByBizNo(req.bizNo())) return mapper.getByBizNo(req.bizNo()); // 幂等
        mapper.insert(Order.from(req));
        // ❌ 禁止：远程调用放事务内（网络慢 → 行锁长期不释放 → 雪崩）
        // inventory.deduct(req.skuId(), req.quantity());
        return OrderConvert.INSTANCE.toVO(po);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)   // 独立事务：日志必须落库
    public void audit(Long orderId, String action) { ... }
}

// JPA 的 N+1：默认懒加载，循环访问关联对象触发 N 条 SQL
// ✅ 方案1：@EntityGraph 指定抓取
@EntityGraph(attributePaths = {"items"})
List<Order> findByUserId(Long userId);

// ✅ 方案2：JPQL fetch join
@Query("select distinct o from Order o left join fetch o.items where o.userId = :uid")
List<Order> findWithItems(@Param("uid") Long uid);

// ✅ 方案3：批量查询后内存组装（大数据量最稳）
// 先查 orders，再用 where order_id in (...) 一次性查 items，Map 分组回填

// MyBatis 防注入：#{} 预编译，${} 是字符串拼接（仅限动态表名/排序且需白名单）
// ✅ WHERE email = #{email}     ❌ WHERE email = '${email}'

// 连接池 HikariCP（Spring Boot 默认）
spring.datasource.hikari.maximum-pool-size=20        # ≈ CPU*2+磁盘，非越大越好
spring.datasource.hikari.connection-timeout=3000     # 拿不到连接快速失败，别让线程堆积
spring.datasource.hikari.leak-detection-threshold=60000   # 检测连接泄漏

// 迁移 Flyway：V1__init.sql / V2__add_index.sql，只在 CI 中顺向执行

// ❌ 禁止 Executors.newFixedThreadPool：队列无界 → OOM
// ✅ 手动创建 ThreadPoolExecutor，明确队列与拒绝策略
@Bean
public ThreadPoolExecutor bizExecutor() {
    return new ThreadPoolExecutor(
        8, 16, 60, TimeUnit.SECONDS,
        new ArrayBlockingQueue<>(500),                 // 有界队列
        new ThreadFactoryBuilder().setNameFormat("biz-%d").build(),  // 命名便于排查
        new ThreadPoolExecutor.CallerRunsPolicy());    // 反压：让调用方自己执行
}

// 并行编排
CompletableFuture<User> u  = supplyAsync(() -> userSvc.get(id), pool);
CompletableFuture<List<Order>> o = supplyAsync(() -> orderSvc.list(id), pool);
return u.thenCombine(o, UserDetail::of).orTimeout(2, TimeUnit.SECONDS).join();

// JDK 21 虚拟线程：IO 密集场景可显著提升吞吐（无需池化，一个请求一个线程）
@Bean TomcatProtocolHandlerCustomizer<?> vt() {
    return h -> h.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
}
// ★ 虚拟线程不解决 CPU 密集问题；synchronized 会 pin 住载体线程（改用 ReentrantLock）

-Xms2g -Xmx2g                    # 堆大小固定，避免动态扩缩抖动（必须等值）
-XX:+UseG1GC -XX:MaxGCPauseMillis=200     # 大堆低延迟首选 G1；JDK17+ 可试 ZGC
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp   # OOM 自动留现场
-Xlog:gc*:file=/logs/gc.log:time,uptime:filecount=5,filesize=50m
-Duser.timezone=Asia/Shanghai -Dfile.encoding=UTF-8     # 时区与编码，必配
-XX:NativeMemoryTracking=summary   # 排查堆外内存泄漏

# 线上排查三件套
jps -l                    # 找 pid
jstack <pid> > stack.txt  # 线程栈（查死锁、线程池打满、CPU 飙高）
jmap -histo <pid> | head -30     # 对象直方图（查内存泄漏）
jstat -gcutil <pid> 1000         # 每秒 GC 情况
arthas                    # 阿里开源，在线诊断神器（watch/trace/dashboard）

@SpringBootTest
@Testcontainers          // 起真实数据库/Redis，比 H2 更贴近生产
class OrderServiceTest {
    @Container static PostgreSQLContainer<?> pg =
        new PostgreSQLContainer<>("postgres:16-alpine");

    @MockBean InventoryClient inventory;         // 隔离外部依赖
    @Autowired OrderService orderService;

    @Test void 缺货时下单失败() {
        when(inventory.deduct(anyLong(), anyInt())).thenReturn(false);
        assertThrows(BizException.class, () -> orderService.create(req));
        verify(orderMapper, never()).insert(any());     // 断言副作用未发生
    }
}

// 可观测：Actuator + Micrometer + OpenTelemetry
management.endpoints.web.exposure.include=health,info,metrics,prometheus
management.endpoint.health.probes.enabled=true     # K8s 就绪/存活探针
// 自定义业务指标（下单成功率、支付耗时）比 JVM 指标更有价值

FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn -B dependency:go-offline          # 依赖层单独缓存
COPY src ./src
RUN mvn -B -DskipTests package

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
# ★ 用 jar 分层（spring-boot 已支持 layertools），改代码只传应用层
COPY --from=build /app/target/app.jar app.jar
RUN adduser -S app && chown app app.jar
USER app
ENTRYPOINT ["java","-XX:+UseContainerSupport","-XX:MaxRAMPercentage=75",\
            "-XX:+ExitOnOutOfMemoryError","-jar","/app.jar"]
# ★ 必加 UseContainerSupport：让 JVM 识别容器内存限制，否则按宿主机内存分配堆

git switch -c feat/x          # 新建并切换分支
git restore --staged file     # 取消暂存
git restore file              # 丢弃工作区修改
git commit --amend --no-edit  # 补进上一次提交
git rebase -i HEAD~3          # 交互式整理提交
git log --oneline --graph -20 # 图形化看历史
git diff main...HEAD          # 看分支相对 main 的全部改动
git bisect start/bad/good     # 二分定位引入 bug 的提交
git worktree add ../hotfix main   # 多工作区并行开发

docker compose up -d --build          # 构建并后台启动
docker compose logs -f app --tail 100 # 跟踪日志
docker compose exec db psql -U postgres
docker system df / docker system prune -a   # 查看/清理磁盘占用
docker stats                          # 实时资源占用
docker build --build-arg BUILDKIT_INLINE_CACHE=1 -t app .
docker image history app:latest       # 分析镜像层体积
COPY --chown=app:app ...              # 避免 root 权限问题

# 端口与连接
lsof -i :3000          # 谁占用了端口
ss -lntp               # 监听端口
ss -s                  # 连接总数统计（查 TIME_WAIT 堆积）

# 资源
top / htop             # CPU 内存
iostat -x 1            # 磁盘 IO（%util 接近 100 说明磁盘瓶颈）
vmstat 1               # 上下文切换、swap
df -h / du -sh *|sort -h   # 磁盘空间

# 日志与进程
journalctl -u app -f --since "10 min ago"
tail -f app.log | grep --color ERROR
strace -p <pid>        # 跟踪系统调用（慎用，影响性能）
kill -TERM <pid>       # 优雅退出；-9 是最后手段

-- 窗口函数：分组内排名 / 去重取最新一条
SELECT * FROM (
  SELECT *, ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC) rn
  FROM orders
) t WHERE rn = 1;

-- CTE：可读性 + 递归查询（组织树、菜单树）
WITH RECURSIVE tree AS (
  SELECT id,name,parent_id FROM dept WHERE parent_id IS NULL
  UNION ALL
  SELECT d.id,d.name,d.parent_id FROM dept d JOIN tree t ON d.parent_id=t.id
) SELECT * FROM tree;

-- 分组统计 + 条件聚合
SELECT date_trunc('day',created_at) d,
       count(*) total,
       count(*) FILTER (WHERE status=1) paid    -- Pg 的条件聚合
FROM orders GROUP BY 1 ORDER BY 1 DESC;

-- 批量 upsert / 去重插入
INSERT INTO tag(name) VALUES ('a'),('b') ON CONFLICT (name) DO NOTHING;

uv venv && source .venv/bin/activate      # 虚拟环境（uv 比 pip 快 10~100 倍）
uv add fastapi / uv add --dev pytest ruff mypy
uv run python -m app.main                  # 免激活执行
pip install -e . / pip-compile pyproject.toml

uv run pytest -q --cov=app --cov-report=term-missing    # 测试 + 覆盖率
uv run pytest -k "user and not slow" -x -vv             # 过滤 + 首次失败即停
ruff check . --fix && ruff format .                    # lint + 格式化
mypy app                                                # 静态类型检查

python -m cProfile -s cumulate app.py      # 性能剖析
python -m py_compile / python -X importtime -c "import app"   # 查慢导入
pipdeptree / uv tree                       # 依赖树，查冲突来源

# Maven
mvn -B clean package -DskipTests           # 打包（-B 非交互，CI 必加）
mvn -B dependency:tree                     # 依赖树，查冲突
mvn -B dependency:go-offline               # 预下载依赖（Docker 分层缓存用）
mvn -B versions:display-dependency-updates # 检查可升级依赖
mvn -T 1C clean install                    # 并行构建多模块

# Gradle
./gradlew bootJar          ./gradlew test --tests '*OrderServiceTest'
./gradlew dependencies --configuration runtimeClasspath

# 运行时排查
jps -l                                     # 列出 Java 进程
jstack <pid> | grep -A20 "BLOCKED"         # 查死锁 / 线程阻塞
jmap -histo <pid> | head -30               # 对象直方图，定位内存泄漏
jstat -gcutil <pid> 1000                   # 每秒 GC 概况
jcmd <pid> VM.native_memory summary        # 堆外内存
java -XX:+PrintFlagsFinal -version | grep HeapSize   # 查看默认堆大小

# 反向代理（必须带这些头，否则后端拿不到真实信息）
location /api/ {
  proxy_pass http://app:3000/;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_connect_timeout 5s;  proxy_read_timeout 60s;
}

# SPA history 路由
location / { try_files $uri $uri/ /index.html; }

# 静态资源长缓存
location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; }

# 限流（需先在 http 块定义 limit_req_zone）
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ { limit_req zone=api burst=20 nodelay; }

# SSE 必须关缓冲
proxy_buffering off;  proxy_cache off;  chunked_transfer_encoding on;

# 项目体检
npx depcheck                       # 找未使用依赖
npx madge --circular src           # 找循环依赖
npx knip                           # 找未使用文件/导出/类型
pnpm audit --audit-level=high      # 安全漏洞
pnpm why <pkg>                     # 谁依赖了它
pnpm dlx npm-check-updates -i      # 交互式升级依赖

# 排查
node --inspect-brk dist/main.js    # 断点调试
node --cpu-prof --heap-prof app.js # 生成性能剖析文件
npx clinic doctor -- node app.js   # 自动诊断性能问题