企业官网建设流程全解析

Feature: User Management API

【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills

Overview

Complete CRUD API for user management with authentication and authorization.

Endpoints

Create User

POST /api/v1/users

Request: { "email": "user@example.com", "name": "John Doe", "password": "SecurePass123!" }

Response (201): { "id": "usr_abc123", "email": "user@example.com", "name": "John Doe", "createdAt": "2025-01-15T10:00:00Z" }

Authentication

All endpoints except POST /users require Bearer token: Authorization: Bearer <jwt_token>

Error Responses

422 Validation Error: { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": { "email": ["Must be valid email"] } } }

注意文档中的 `POST /api/v1/users` 采用了 [api-design-standards.md](https://link.gitcode.com/i/1ef7c537efef4f2acadee66ebd0f0df5) 推荐的**URL 路径版本化**（`/api/v1/...`）。技术文档应当用 `POST`/`GET`/`PUT`/`PATCH`/`DELETE` 与 200/201/204/400/401/403/404/409/422/429 等状态码把每个端点的语义写清，并统一错误格式，方便前端直接对齐实现。 ### 组件文档（JSDoc 风格） 对复用价值高的组件，用 JSDoc 记录用途、参数与示例： ```typescript /** * UserProfileForm - Editable user profile form with validation * * @example * <UserProfileForm * initialData={currentUser} * onSubmit={handleUpdate} * onCancel={() => router.back()} * /> * * @param initialData - User data to pre-populate form * @param onSubmit - Callback when form is submitted with valid data * @param onCancel - Optional callback when user cancels editing */ export function UserProfileForm({ initialData, onSubmit, onCancel }: UserProfileFormProps) { // Component implementation }

一份好的组件文档应让使用者不看实现代码就能正确调用组件——示例代码、参数语义、可选/必选约束都在注释中讲清楚。

README 更新

• 安装说明（Installation instructions）
• 环境变量配置（Environment variable configuration）
• 开发环境搭建步骤（Development setup steps）
• 构建与部署命令（Build and deployment commands）
• 测试说明（Testing instructions）
• 故障排查指南（Troubleshooting guide）

README 是项目的第一入口，清单要求把环境变量、开发启动、构建部署、测试运行与排障全部写清楚，让新人（或未来的你）拿到仓库即可跑通。

Storybook 文档（前端）

对组件库型项目，Storybook 是组件"活文档"：

// UserCard.stories.tsx export default { title: 'Components/UserCard', component: UserCard, } as Meta; export const Default: Story = { args: { user: { name: 'John Doe', email: 'john@example.com', avatar: 'https://example.com/avatar.jpg', }, }, }; export const Loading: Story = { args: { isLoading: true }, }; export const WithLongName: Story = { args: { user: { name: 'Johnathan Alexander Wellington III', email: 'johnathan@example.com', }, }, };

注意WithLongName这个 Story：它专门覆盖"超长用户名不破坏布局"的边缘场景。好的 Storybook 不只展示默认态，更要展示 loading、空数据、超长文本、错误态等边界状态，让设计师与开发者直观审查各种条件下的表现。

五、性能交付物（Performance Deliverables）

性能不是上线后才发现的问题，而是交付前必须度量的交付物。

性能指标报告

## Performance Metrics ### Backend API - Average response time: 45ms - P95 response time: 120ms - P99 response time: 250ms - Throughput: 1000 req/s - Error rate: 0.02% ### Frontend Bundle - Initial bundle size: 245 KB (gzipped) - Largest chunk: 180 KB - Time to Interactive: 1.2s - Lighthouse score: 95/100 ### Database Queries - Average query time: 15ms - Slowest query: 85ms (user search) - Index usage: 98% - Connection pool utilization: 60%

重要说明：以上数字是清单给出的示例指标形态与记录格式，并非针对本仓库的实测数据。每个项目应基于自身压测工具（k6、JMeter、Locust 等）与真实环境重新测量。报告的价值在于它的结构：后端关注延迟分位数（P95/P99 而非仅平均值）、吞吐与错误率；前端关注打包体积与 TTI（Time to Interactive）；数据库关注慢查询与索引使用率。速查表给出的参考目标为 API P95 < 200ms、前端 TTI < 2s，可作基线。

打包分析

• Webpack/Vite 打包分析报告
• Lighthouse 性能审计
• Core Web Vitals 测量
• 打包体积对比（改动前/后）

"打包体积对比"是关键动作：每次功能合入前后各测一次，才能量化"这个功能让包涨了多少 KB"，防止包体无声膨胀。

六、安全交付物（Security Deliverables）

安全是fullstack-guardian的立身之本，交付物清单给出了安全验收的完整闭环。

安全检查清单

• 所有端点做输入校验（Input validation on all endpoints）
• 输出净化，防 XSS（Output sanitization）
• 参数化查询防 SQL 注入（SQL injection prevention）
• 开启 CSRF 防护（CSRF protection enabled）
• 配置限流（Rate limiting configured）
• 需要处强制鉴权（Authentication required where needed）
• 实现授权检查（Authorization checks implemented）
• 响应排除敏感数据（Sensitive data excluded from responses）
• 密钥放环境变量（Secrets in environment variables）
• 生产强制 HTTPS（HTTPS enforced in production）
• 配置安全响应头（CSP、HSTS 等）

这 11 项直接对应 security-checklist.md 的六大检查维度：Auth（端点是否要求认证）、Authz（用户是否有权操作）、Input（输入是否校验净化）、Output（响应是否过滤敏感字段）、Rate Limit（是否限流）、Logging（安全事件是否记录）。其中限流的典型实现：

// Express rate-limit：登录端点从严 const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15 分钟窗口 max: 5, // 最多 5 次尝试 message: 'Too many login attempts', }); app.post('/login', authLimiter, loginHandler);

结合 api-design-standards.md，更完整的分层限流方案是：全站通用限流（如 100 req/15min/IP）+ 认证类端点更严的独立限流（如 5 req/15min），必要时改用 Redis 支撑（rate-limiter-flexible），在分布式/多实例部署下保持限流计数一致。

安全审计报告

安全审计报告把防护措施落到具体技术参数：

## Security Review ### Authentication - JWT with RS256 algorithm - 15-minute access tokens - 7-day refresh tokens - Secure cookie storage ### Authorization - Role-based access control (RBAC) - Resource ownership validation - Permission checks on all mutations ### Data Protection - Passwords hashed with bcrypt (12 rounds) - Sensitive data encrypted at rest - PII excluded from logs - Rate limiting: 100 req/15min per IP

这份报告的价值在于可审计性：算法（RS256）、令牌有效期（15 分钟 access / 7 天 refresh）、哈希轮数（bcrypt 12 rounds）、限流额度（100 req/15min）都以具体数字呈现，安全评审者无需翻代码即可评估风险。报告内容与 SKILL.md 的"三视角示例"相互印证：鉴权必须由后端强制（服务端 dependency/guard），响应 Schema 显式排除敏感字段，越权时在访问数据库之前就返回 403，避免时序侧信道。

七、部署交付物（Deployment Deliverables）

配置文件

• 多阶段构建的Dockerfile（multi-stage build）
• 本地开发用docker-compose.yml
• CI/CD 流水线配置
• 环境差异化配置
• 数据库迁移脚本
• 健康检查端点
• Kubernetes 清单（如适用）

多阶段 Dockerfile 的价值在于"构建环境与运行环境分离"：构建阶段安装全部依赖、产出产物，运行阶段仅保留最小运行时镜像，显著缩小镜像体积并减少攻击面。健康检查端点与 CI/CD、容器编排（k8s liveness/readiness probe）直接联动，是"零停机部署"的前提。

部署指南

## Deployment Steps ### Prerequisites - Node.js 18+ - PostgreSQL 15+ - Redis 7+ ### Environment Variables DATABASE_URL=postgresql://user:pass@host:5432/dbname REDIS_URL=redis://localhost:6379 JWT_SECRET=<generate-secure-secret> API_PORT=3000 ### Build & Deploy npm run build npm run migrate npm run start:prod ### Health Check GET /api/health Expected: { "status": "ok", "database": "connected" }

【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills