概述

相关源文件

• .github/CODEOWNERS
• .github/ISSUE_TEMPLATE/BUG_REPORT.yml
• .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml
• README.md
• api/openapi.yml
• apps/api/package.json
• apps/api/prisma/dev.db
• apps/api/prisma/migrations/20241009081140_init/migration.sql
• apps/api/prisma/migrations/migration_lock.toml
• package.json

RealWorld 项目是一个标准化的 API 实现和参考平台，旨在展示如何使用各种前端和后端技术构建真实的应用程序。与仅展示基本功能的典型“待办事项”演示不同，RealWorld 提供了完整的、可用于生产环境的应用程序，具有 CRUD 操作、身份验证、路由、分页等功能。

本文档涵盖了 RealWorld 平台的核心架构、组件和工作流程。有关具体的实现细节，请参阅 项目结构 或 入门指南。

来源： README.md8-12 package.json8

系统架构

RealWorld 的设计围绕一套标准化的接口，这些接口允许前端和后端实现互换，同时保持功能的一致性。

该架构的特点是规范（任何实现都必须遵循）与实现本身之间存在清晰的分离。这使得开发人员可以专注于他们选择的技术，同时确保与所有其他实现的兼容性。

来源： README.md30-34 api/openapi.yml1-5 package.json3-16

核心组件

API 规范

API 规范以 OpenAPI 格式定义，是 RealWorld 的基础。它提供了对以下内容的正式定义：

• 身份验证端点
• 用户和个人资料管理
• 文章创建、检索和修改
• 评论功能
• 标签管理
• 收藏文章功能

来源： api/openapi.yml12-19 api/openapi.yml22-421

数据库 Schema

数据库模式使用 Prisma 定义，对域实体及其关系进行建模。

来源： apps/api/prisma/migrations/20241009081140_init/migration.sql1-95

API 测试系统

RealWorld 包括一个全面的 API 测试套件，使用 Postman Collections 来验证实现正确性。

来源： README.md31

开发工作流

RealWorld 项目使用 monorepo 结构，由 pnpm 和 Turbo 管理，以实现高效的开发和构建。

来源： package.json24-28 apps/api/package.json3-10

实施目标

RealWorld 的目的是提供：

1. 一个真实的示例应用程序，超越简单的“待办事项”应用
2. 所有实现的标准 API 规范
3. 一个展示最佳实践的参考实现
4. 一个用于验证实现正确性的测试系统
5. 一种展示遵循相同规范的不同前端和后端技术的方式

该项目鼓励开发人员使用不同的语言和框架创建新的实现，同时通过标准化的 API 确保兼容性。

来源： README.md8-15 README.md17-20 README.md30-34

技术栈

参考实现使用以下技术：

组件	技术
API服务器	Nitro/Node.js
数据库	Prisma with SQLite
API 定义	OpenAPI 3.0.1
API 测试	Postman Collection
包管理	pnpm
构建系统	Turbo
身份验证	JWT 令牌

来源： apps/api/package.json3-25 api/openapi.yml1-4 package.json24-36

集成点

开发人员实施 RealWorld 的关键集成点包括：

1. API 端点 - 必须符合 OpenAPI 规范
2. 数据模型 - 必须支持 Prisma schema 中定义的实体关系
3. 身份验证 - 必须实现基于 JWT 令牌的身份验证系统
4. API 验证 - 实现应通过 Postman collection 中的所有测试

这些集成点可确保任何实现，无论技术栈如何，都能与 RealWorld 生态系统兼容。

来源： README.md30-34 api/openapi.yml823-836