企业官网建设流程全解析

天津网站开发培训,湖北免费相亲网站,南宁手机做网站公司,郑州做网站网络公司#x1f4d6; 写在前面在 AI 编程快速发展的 2025 年#xff0c;一种新的开发范式正在崛起#xff1a;SDD#xff08;Specification-Driven Development#xff0c;规范驱动开发#xff09;。传统开发中#xff0c;我们与 AI 的对话往往是随意的、模糊的#xff0c;导致… 写在前面在 AI 编程快速发展的 2025 年一种新的开发范式正在崛起SDDSpecification-Driven Development规范驱动开发。传统开发中我们与 AI 的对话往往是随意的、模糊的导致 AI 生成幻觉代码或偏离需求。SDD 的核心思想是在写代码之前先让 AI 和人类对要构建什么达成明确的共识。本文将深入介绍 SDD 领域的两个核心工具GitHub SpecKit和Fission-AI OpenSpec帮助您理解如何在 AI 编程中实现真正的意图锁定。 一、什么是 SDD规范驱动开发1.1 核心定义SDDSpecification-Driven Development是一种规范优先的软件开发方法论其核心原则是┌─────────────────────────────────────────────────────────────────┐ │ SDD 开发流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. 【锁定意图】先写规范Specification │ │ └─ 明确定义构建什么What │ │ │ │ 2. 【生成计划】AI 根据规范创建实现计划 │ │ └─ 规划如何实现How │ │ │ │ 3. 【生成任务】将计划拆解为可执行任务 │ │ └─ 具体的实施步骤 │ │ │ │ 4. 【实现代码】AI 按照任务生成代码 │ │ └─ 代码只是最后一公里 │ │ │ │ 5. 【测试验证】验证是否符合规范 │ │ └─ 确保实现与规范一致 │ │ │ └─────────────────────────────────────────────────────────────────┘1.2 SDD vs 传统开发维度传统 AI 编程SDD 规范驱动开发沟通方式随意对话、模糊指令结构化规范文档核心资产代码规范Specification意图锁定❌ 容易偏离✅ 先达成共识可追溯性❌ 难以回溯✅ 规范即文档AI 幻觉❌ 高风险✅ 约束明确质量保证事后修复事前验证1.3 SDD 的核心价值┌─────────────────────────────────────────────────────────────────┐ │ SDD 的四大价值 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. 【锁定意图】 │ │ └─ 在写代码前你和 AI 先对要做什么达成共识 │ │ │ │ 2. 【减少幻觉】 │ │ └─ 规范约束了 AI 的输出范围避免胡乱发挥 │ │ │ │ 3. 【可审计性】 │ │ └─ 每次变更都有明确的规范记录便于审查和回溯 │ │ │ │ 4. 【可维护性】 │ │ └─ 规范成为活的文档与代码同步演进 │ │ │ └─────────────────────────────────────────────────────────────────┘️ 二、GitHub SpecKit结构化的 SDD 工具2.1 什么是 SpecKit定义SpecKit 是 GitHub 官方开源的规范驱动开发工具包提供了一套完整的命令行工具帮助开发者通过结构化的规范文档与 AI 协作。官方仓库github.com/github/spec-kit核心特点✅ 官方出品GitHub 背书✅ 结构化工作流7个标准命令✅ 内置 TDD 测试框架✅ 适合从零开始的新项目Greenfield✅ 开源免费43.7k GitHub Stars2.2 SpecKit 的七个核心命令# SpecKit 标准工作流7个命令命令 1/speckit.constitution- 创建项目治理原则作用定义项目的开发准则、技术栈选择、代码规范等元规则。示例# 项目 Constitution ## 技术栈 - 语言: Python 3.11 - 框架: FastAPI - 数据库: PostgreSQL - 测试: pytest ## 开发准则 - 遵循 PEP 8 代码规范 - 所有函数必须有类型注解 - 测试覆盖率不低于 80% - 提交前必须通过 lint 检查 ## 架构原则 - 分层架构: Handler → Service → Repository - 依赖注入: 使用 fastapi.Depends - 错误处理: 统一异常处理器命令 2/speckit.specify- 描述需求作用明确描述要构建什么包括功能需求、非功能需求、约束条件。示例# 用户认证功能 Specification ## 功能概述 实现基于 JWT 的用户认证系统支持登录、注册、令牌刷新。 ## 功能需求 1. 用户注册 - 输入: email, password, username - 输出: 用户 ID JWT access token - 验证: email 格式、密码强度8位以上大小写字母数字 2. 用户登录 - 输入: email, password - 输出: JWT access token (15分钟有效) refresh token (7天有效) 3. 令牌刷新 - 输入: refresh token - 输出: 新的 access token ## 非功能需求 - 性能: 登录响应时间 200ms - 安全: 密码使用 bcrypt 哈希cost12 - 可用性: 99.9% SLA ## 约束条件 - 不支持第三方登录Google/GitHub - 不支持密码找回功能后续版本命令 3/speckit.clarify- 需求澄清作用AI 主动提问澄清需求中的模糊点确保规范完整无歧义。示例输出# 澄清问题 以下问题需要明确 1. [登录失败] 登录失败时是否返回具体原因密码错误 vs 用户不存在 推荐答案: 返回通用错误信息防止用户枚举 2. [令牌存储] 客户端应如何存储 refresh token 选项: A) localStorage B) httpOnly cookie C) 内存 推荐答案: B) httpOnly cookie更安全 3. [并发登录] 是否允许同一用户多个设备同时登录 选项: A) 允许 B) 仅允许一个活跃令牌 推荐答案: A) 允许第一阶段命令 4/speckit.plan- 创建技术实现计划作用AI 根据规范生成详细的技术实现方案。示例输出# 技术实现计划 ## 架构设计 ### 数据模型User 表:id: UUID (PK)email: VARCHAR(255) UNIQUEpassword_hash: VARCHAR(255)username: VARCHAR(50)created_at: TIMESTAMPupdated_at: TIMESTAMPRefreshToken 表:id: UUID (PK)user_id: UUID (FK)token_hash: VARCHAR(255)expires_at: TIMESTAMP### API 设计POST /api/v1/auth/register POST /api/v1/auth/login POST /api/v1/auth/refresh POST /api/v1/auth/logout### 安全措施 - 密码: bcrypt (cost12) - JWT: HS256 算法密钥从环境变量读取 - Rate Limiting: 每个 IP 每分钟最多 10 次登录尝试实现顺序搭建项目骨架FastAPI SQLAlchemy实现数据模型和数据库迁移实现密码哈希工具函数实现 JWT 工具函数实现 /register 端点实现 /login 端点实现 /refresh 端点编写集成测试#### 命令 5/speckit.tasks - 生成可执行任务 **作用**将实现计划拆解为具体的、可执行的任务列表。 **示例输出** markdown # 任务列表 ## Phase 1: 基础设施 (30分钟) - [ ] Task 1.1: 初始化 FastAPI 项目结构 - [ ] Task 1.2: 配置 SQLAlchemy 和 PostgreSQL 连接 - [ ] Task 1.3: 创建 Alembic 迁移配置 ## Phase 2: 数据层 (1小时) - [ ] Task 2.1: 定义 User 模型 - [ ] Task 2.2: 定义 RefreshToken 模型 - [ ] Task 2.3: 创建数据库迁移脚本 - [ ] Task 2.4: 编写 Repository 基类 ## Phase 3: 业务逻辑 (2小时) - [ ] Task 3.1: 实现密码哈希服务 - [ ] Task 3.2: 实现 JWT 令牌服务 - [ ] Task 3.3: 实现注册服务 - [ ] Task 3.4: 实现登录服务 - [ ] Task 3.5: 实现令牌刷新服务 ## Phase 4: API 层 (1.5小时) - [ ] Task 4.1: 实现 /register 端点 - [ ] Task 4.2: 实现 /login 端点 - [ ] Task 4.3: 实现 /refresh 端点 - [ ] Task 4.4: 添加全局异常处理器 ## Phase 5: 测试 (1.5小时) - [ ] Task 5.1: 编写单元测试服务层 - [ ] Task 5.2: 编写集成测试API 层 - [ ] Task 5.3: 配置 CI/CD 流水线命令 6/speckit.implement- 实现代码作用AI 根据任务列表逐个生成代码实现。示例# Task 3.1: 实现密码哈希服务 # src/services/password_service.py import bcrypt from typing import str class PasswordService: staticmethod def hash_password(password: str) - str: 使用 bcrypt 哈希密码 salt bcrypt.gensalt(rounds12) return bcrypt.hashpw(password.encode(utf-8), salt).decode(utf-8) staticmethod def verify_password(password: str, hashed: str) - bool: 验证密码 return bcrypt.checkpw(password.encode(utf-8), hashed.encode(utf-8))命令 7/speckit.test- 运行测试作用SpecKit 独有的 TDD 支持自动生成测试代码并验证实现。特点✅ 内置测试框架✅ 自动生成测试用例✅ 强制测试驱动开发TDD2.3 SpecKit 安装与使用环境要求- Python ≥ 3.11 - uv 包管理器 - Linux / macOS / Windows WSL2安装步骤# 1. 安装 uv 包管理器 curl -LsSf https://astral.sh/uv/install.sh | sh # 2. 安装 SpecKit uv tool install specify-cli --from githttps://github.com/github/spec-kit # 3. 验证安装 specify --help # 4. 初始化项目 specify init快速开始# 创建新项目 mkdir my-sdd-project cd my-sdd-project specify init # 按照工作流执行 /speckit.constitution # 创建项目准则 /speckit.specify # 描述需求 /speckit.clarify # 澄清需求可选 /speckit.plan # 生成实现计划 /speckit.tasks # 生成任务列表 /speckit.implement # 实现代码 /speckit.test # 运行测试2.4 SpecKit 最佳实践DO应该做的✓ 严格按照 7 个命令的顺序执行 ✓ 在 /speckit.specify 阶段尽可能详细地描述需求 ✓ 重视 /speckit.clarify 阶段回答 AI 的所有问题 ✓ 每个任务完成后运行 /speckit.test 验证 ✓ 将规范文档纳入版本控制DONT不应该做的✗ 跳过 /speckit.clarify 阶段 ✗ 在 /speckit.specify 阶段就开始写代码 ✗ 忽略测试直接进入实现 ✗ 规范文档不同步代码变更 ✗ 使用 SpecKit 维护遗留代码应使用 OpenSpec 三、Fission-AI OpenSpec轻量级的 SDD 框架3.1 什么是 OpenSpec定义OpenSpec 是由 Fission-AI 团队开发的轻量级、便携式规范驱动开发框架专为 AI 编程助手设计。官方资源GitHub: github.com/Fission-AI/OpenSpec官网: openspec.dev核心特点✅ 轻量级便携单个 npm 包✅ 无需 API 密钥✅ 适合现有项目Brownfield✅ 活文档架构每次变更自动归档✅ 与 Claude Code、Cursor、Codex 等深度集成3.2 OpenSpec vs SpecKit维度SpecKitOpenSpec开发团队GitHub 官方Fission-AI适用场景从零开始的新项目现有项目的增量开发结构化程度高7个标准命令中3个核心命令TDD 支持✅ 内置强制 TDD❌ 需自行配置安装复杂度中需要 Python uv低npm 全局安装文档风格结构化规范文件提案ProposalMarkdown学习曲线较陡较平缓3.3 OpenSpec 的三个核心命令命令 1openspec proposal- 创建变更提案作用为 AI 创建结构化的 Markdown 提案文档描述要实现的变更。示例# 创建提案 openspec proposal # AI 会生成以下结构# Proposal: 添加用户认证功能 ## 提案概述 本提案旨在为系统添加基于 JWT 的用户认证功能。 ## 项目背景 当前系统没有任何认证机制所有端点都是公开的。为了保护敏感数据和操作需要实现用户认证。 ## 拟议方案 ### 功能需求 1. 用户注册 2. 用户登录 3. 令牌刷新 ### 技术栈 - FastAPI - JWT (PyJWT) - bcrypt 密码哈希 - PostgreSQL 存储 ### 实现约束 - 遵循现有项目架构 - 不破坏现有 API - 向后兼容 ## 预期成果 - 完整的认证系统 - 单元测试覆盖率 80% - API 文档更新 ## 时间估算 - 开发时间: 6 小时 - 测试时间: 2 小时命令 2openspec apply- 应用提案作用AI 根据提案文档生成代码实现。示例# 应用提案 openspec apply # AI 会 # 1. 分析提案文档 # 2. 生成实现代码 # 3. 生成测试代码 # 4. 更新文档命令 3openspec archive- 归档变更作用将已完成的变更归档到活文档中保持文档与代码同步。示例# 归档变更 openspec archive # 效果 # - 将 proposal 移动到 docs/archive/ 目录 # - 更新 CHANGELOG.md # - 生成变更总结3.4 OpenSpec 工作流程┌─────────────────────────────────────────────────────────────────┐ │ OpenSpec 工作流 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. 【创建提案】openspec proposal │ │ └─ 生成 proposal.md 文档 │ │ │ │ 2. 【审核提案】人工审查提案 │ │ └─ 确认需求、技术方案、时间估算 │ │ │ │ 3. 【应用提案】openspec apply │ │ └─ AI 生成代码 测试 │ │ │ │ 4. 【验证实现】人工测试 CI/CD │ │ └─ 确保符合提案要求 │ │ │ │ 5. 【归档变更】openspec archive │ │ └─ 更新活文档保持可追溯性 │ │ │ └─────────────────────────────────────────────────────────────────┘3.5 OpenSpec 安装与使用安装步骤# 1. 全局安装 OpenSpec npm install -g fission-ai/openspeclatest # 2. 验证安装 openspec --help # 3. 初始化项目在现有项目中 cd your-existing-project openspec init快速开始# 在现有项目中添加新功能 openspec proposal # 创建提案 # 编辑 proposal.md openspec apply # 应用提案 # 审查代码、运行测试 openspec archive # 归档变更3.6 OpenSpec 的活文档架构OpenSpec 的独特之处在于其活文档Living Documentation设计项目结构: ├── docs/ │ ├── proposal.md # 当前进行中的提案 │ ├── archive/ # 已归档的提案 │ │ ├── 001-add-auth.md │ │ ├── 002-add-payment.md │ │ └── ... │ └── CHANGELOG.md # 自动生成的变更日志 ├── src/ # 源代码 └── tests/ # 测试代码每次归档后proposal.md被移动到docs/archive/目录CHANGELOG.md自动更新项目的变更历史完整可追溯 四、如何选择SpecKit vs OpenSpec4.1 决策树你的项目是 │ ├─ 从零开始的新项目 │ └─ 使用 SpecKit │ └─ 完整的结构化工作流 │ └─ 内置 TDD 支持 │ └─ 现有项目需要添加新功能 └─ 使用 OpenSpec └─ 轻量级集成 └─ 活文档架构4.2 详细对比场景推荐工具原因全新项目SpecKit完整工作流从零开始建立规范遗留代码OpenSpec轻量级不会破坏现有结构需要 TDDSpecKit内置测试框架强制测试驱动快速原型OpenSpec学习曲线低上手快团队协作SpecKit结构化规范便于审查个人开发OpenSpec简单灵活自由度高4.3 组合使用场景大型项目新功能 遗留维护# 新模块使用 SpecKit mkdir new-payment-system cd new-payment-system specify init # ... SpecKit 工作流 # 遗留模块使用 OpenSpec cd legacy-user-system openspec init # ... OpenSpec 工作流 五、SDD 实战案例5.1 案例使用 SpecKit 构建 REST API需求构建一个简单的图书管理 API# 1. 初始化项目 specify init # 2. 创建项目准则 /speckit.constitution生成的 constitution.md# 图书管理 API 项目准则 ## 技术栈 - 语言: Python 3.11 - 框架: FastAPI - 数据库: SQLite开发/ PostgreSQL生产 - ORM: SQLAlchemy - 测试: pytest ## 代码规范 - 遵循 PEP 8 - 所有函数必须有类型注解 - API 文档使用 OpenAPI 规范 ## 架构原则 - 分层架构: Router → Service → Repository - 依赖注入 - 统一错误处理# 3. 描述需求 /speckit.specify生成的 specification.md# 图书管理 API 需求规范 ## 功能概述 实现一个 RESTful API支持图书的增删改查操作。 ## 功能需求 ### 1. 创建图书 - 端点: POST /api/v1/books - 输入: title, author, isbn, publication_year - 输出: 图书 ID 完整图书信息 - 验证: - title: 必填1-200 字符 - author: 必填1-100 字符 - isbn: 必填符合 ISBN-13 格式 - publication_year: 可选1900-当前年份 ### 2. 查询图书 - 端点: GET /api/v1/books/{id} - 输出: 完整图书信息 - 错误: 404 如果图书不存在 ### 3. 更新图书 - 端点: PATCH /api/v1/books/{id} - 输入: 部分图书字段 - 输出: 更新后的图书信息 ### 4. 删除图书 - 端点: DELETE /api/v1/books/{id} - 输出: 204 No Content ### 5. 列出所有图书 - 端点: GET /api/v1/books - 查询参数: page, page_size, author - 输出: 图书列表 分页信息 ## 非功能需求 - 响应时间: 100ms (P95) - 并发: 支持 100 QPS - 可用性: 99% SLA# 4. 澄清需求 /speckit.clarifyAI 提出的问题# 澄清问题 1. [ISBN 唯一性] ISBN 是否应该是全局唯一的 推荐: 是添加唯一索引 2. [软删除] 删除图书是物理删除还是软删除 推荐: 物理删除第一阶段 3. [分页默认值] 列出图书时默认 page_size 是多少 推荐: 20# 5. 生成实现计划 /speckit.plan # 6. 生成任务列表 /speckit.tasks # 7. 实现代码 /speckit.implement # 8. 运行测试 /speckit.test5.2 案例使用 OpenSpec 为现有项目添加功能场景为一个现有的 Django 项目添加导出 PDF 功能cd existing-django-project openspec init # 1. 创建提案 openspec proposal生成的 proposal.md# Proposal: 添加 PDF 导出功能 ## 提案概述 为图书管理页面添加 PDF 导出功能允许用户导出图书列表为 PDF 文件。 ## 项目背景 当前用户只能在线查看图书列表没有离线分享或存档的能力。 ## 拟议方案 ### 功能需求 1. 在图书列表页添加导出 PDF按钮 2. 支持导出当前筛选结果 3. PDF 包含图书封面、标题、作者、ISBN 4. 支持 A4 和 Letter 纸张大小 ### 技术方案 - 使用 reportlab 生成 PDF - 前端添加导出按钮不破坏现有 UI - 后端新增 /api/v1/books/export/pdf 端点 ### 实现约束 - 不修改现有数据模型 - 不影响现有功能 - 向后兼容 ## 预期成果 - 完整的 PDF 导出功能 - 单元测试 - API 文档更新 ## 时间估算 - 开发时间: 3 小时 - 测试时间: 1 小时# 2. 编辑提案确认细节 vim proposal.md # 3. 应用提案 openspec apply # 4. 审查代码 # 5. 运行测试 pytest # 6. 归档变更 openspec archive 总结核心要点SDD规范驱动开发在写代码前先让 AI 和人类对要构建什么达成明确的共识SpecKitGitHub 官方工具结构化工作流适合从零开始的新项目内置 TDD 支持OpenSpecFission-AI 开发轻量级便携适合现有项目活文档架构快速选择项目类型 ├─ 全新项目 │ └─ SpecKit完整工作流 TDD └─ 现有项目 └─ OpenSpec轻量级 活文档设计哲学层面SpecKitOpenSpec核心理念结构化规范提案驱动开发模式Greenfield从零开始Brownfield增量开发文档风格规范文件提案文档质量保证内置 TDD人工审查