内容
# NENE2
[](https://www.php.net/)
[](https://packagist.org/packages/hideyukimori/nene2)
[](https://raw.githubusercontent.com/hideyukiMORI/NENE2/main/docs/openapi/openapi.yaml)
[](./LICENSE)
PHP 微框架：优先考虑 JSON APIs，最小化服务器端 HTML，易于集成 React 启动器，结构友好于 AI 工具。
**[OpenAPI 契约](https://raw.githubusercontent.com/hideyukiMORI/NENE2/main/docs/openapi/openapi.yaml)** — 可机器读取的 API 规范（OpenAPI 3.1）。在运行 `docker compose up -d app` 后，实时 Swagger UI 可在 `http://localhost:8200/docs/` 访问。
NENE2 是一个小型、现代的 PHP 框架基础，适用于希望快速交付 JSON APIs、保持服务器端渲染的 HTML 最小化、并添加 React 前端启动器而不将后端变成前端构建胶水的项目。
`v1.x` 基础涵盖了完整的 Note/Tag CRUD、Bearer JWT 身份验证、分页助手以及六语言 VitePress 文档站点，具有可选的速率限制和数据库健康检查作为生产就绪的可选功能。维护者可以克隆仓库、运行本地 API、共享 OpenAPI 契约、通过 API 边界公开安全 MCP 工具，并在 Docker Compose 中验证数据库行为。
## 项目亮点
NENE2 在开放的环境中构建，以高速率由单个维护者使用 AI 辅助、问题驱动的工作流构建：
- **140+ 版本**（当前：`v1.10.0`）和 **740+ 合并的拉取请求** 自 2026 年 5 月第一个提交以来（截至 2026-07）— 每个更改都通过问题 → 分支 → 拉取请求 → CI 管道落地；直接不提交到 `main`。
- **[262 个操作指南](docs/howto/README.md)** 涵盖身份验证、安全、数据库模式、API 设计、后台作业和 100+ 产品功能配方。
- **[125+ 可运行的示例应用](https://github.com/hideyukiMORI/NENE2-examples)** — 每个都是自包含的 JSON API，带有测试，作为框架本身的现场试验。
- **支持 NeNe 产品家族** — 12+ 开源、自托管的适用于小型团队的商业工具（发票、记录、交易跟踪、联系人管理等），均在此框架上构建并共享其故障关闭的安全基线。
- **文档化的决策** — 每个架构选择都有 ADRs、OpenAPI 3.1 契约、六语言文档和 Smithery 上的 MCP 服务器。
## 主题
- **API 优先**：通过清晰的 HTTP 边界和 OpenAPI 契约定义行为。
- **简单的 HTML**：保持服务器端 HTML 最小化、可预测且易于替换为 SPA 外壳。
- **前端就绪**：提供 React + TypeScript 启动器方向，同时保持前端层可替换。
- **AI 可读**：优先考虑明确的目录、小的类、类型化的边界和文档化的决策。
- **LLM 交付就绪**：保持 API、MCP、身份验证、数据库和交接文档对齐，以适用于小型客户端项目。
- **现代 PHP**：使用严格类型、PSR 导向的样式、依赖注入、自动化测试和静态分析。
## 当前功能
基础目前包括：
- PSR-7 / PSR-15 / PSR-17 HTTP 运行时，具有明确的路由和中间件。
- OpenAPI 契约、Swagger UI 和已发货 JSON 端点的运行时契约测试。
- RFC 9457 问题详情错误响应。
- 通过 `.env` 加载边界的类型化应用和数据库配置。
- 具有明确运行时服务连接线的 PSR-11 依赖注入。
- PDO 连接、查询执行器、事务管理器、SQLite 测试和通过 Docker Compose 可选的 MySQL 验证。
- 带有允许列表、阻止列表和前缀路径选项的 Bearer JWT 中间件；用于三层访问模型（公共 / Bearer / API 密钥）的 `CompositeAuthMiddleware`。
- 故障关闭的 JWT 机密解析（`GuardedJwtSecretResolver`）：生产环境从不接受开发签名密钥，空密钥被视为未设置而不是默默信任。
- 用于机器客户端端点的 API 密钥中间件，带有路径和方法过滤器。
- 通过 `NativePhpViewRenderer` 和 `HtmlResponseFactory` 进行服务器端渲染 HTML — 薄 HTML 与 JSON API 路由共存。
- 本地 MCP 服务器支持用于与 OpenAPI 对齐的读写工具，并在写入操作上具有身份验证保护。
- 用于共享托管设置的选项安装工具包（`Nene2\Install`）：预飞行和配置验证、发布清单处理、数据库架构应用和未品牌化的参考渲染器，在连接之前保持休眠状态。
## 文章
- [我为 AI 可读的商业 API 构建了一个小型 PHP 框架](https://dev.to/hideyukimori/i-built-a-tiny-php-framework-for-ai-readable-business-apis-48eo) — DEV Community 对 NENE2 的 API 优先、OpenAPI 和 MCP 就绪设计的介绍。
- [MCP 不应该意味着让 AI 触摸你的数据库](https://dev.to/hideyukimori/mcp-should-not-mean-letting-ai-touch-your-database-57p1) — DEV Community 关于保持 MCP 工具在文档化的 HTTP/API 边界后面的文章。
## 安装
NENE2 在 [Packagist](https://packagist.org/packages/hideyukimori/nene2) 上可用。
启动新项目的推荐方式是直接克隆仓库 — 它带有 Docker、`.env.example` 和所有您需要的配置：
```bash
git clone https://github.com/hideyukiMORI/NENE2.git my-project
cd my-project
```
如果您想在现有项目中使用 NENE2 作为 Composer 依赖：
```bash
composer require hideyukimori/nene2
```
---
## 快速入门
构建 PHP 运行时、安装依赖并运行标准后端检查：
```bash
cp .env.example .env
docker compose build
docker compose run --rm app composer install
docker compose run --rm app composer check
```
启动本地 Web 运行时：
```bash
docker compose up -d app
```
Web 入口点从 `public_html/` 在 `http://localhost:8200/` 提供。
有用的本地 URL：
- API 健康状况：`http://localhost:8200/health`
- 示例端点：`http://localhost:8200/examples/ping`
- OpenAPI：`http://localhost:8200/openapi.php`
- Swagger UI：`http://localhost:8200/docs/`
## 领域层示例
`src/Example/Note/` 和 `src/Example/Tag/` 是**参考实现** — 它们演示了如何使用框架，但不属于公共 API 稳定性保证的范围（参见 [ADR 0009](docs/adr/0009-v1.0-public-api-scope.md)）。复制并适配模式到您自己的应用程序；不要将这些类作为库依赖导入。
`src/Example/Note/` 实现了一个完整的 Note CRUD，具有：
| 层 | 文件 |
|---|---|
| 路由 + 处理程序 | `GetNoteByIdHandler`、`CreateNoteHandler`、`UpdateNoteHandler`、`DeleteNoteHandler`、`ListNotesHandler` |
| 用例（领域） | `GetNoteByIdUseCase`、`CreateNoteUseCase`、`UpdateNoteUseCase`、`DeleteNoteUseCase`、`ListNotesUseCase` |
| 仓库接口 | `NoteRepositoryInterface` |
| PDO 适配器 | `PdoNoteRepository` |
| 异常映射 | `NoteNotFoundException` → `NoteNotFoundExceptionHandler` → 404 问题详情 |
| OpenAPI | `docs/openapi/openapi.yaml` — `GET/POST/PUT/DELETE /examples/notes` 路径 |
| 测试 | `tests/Example/Note/` — 单元、HTTP 级别、PDO 集成 |
所有 Note 端点在运行 `docker compose up -d app` 后都在 `http://localhost:8200/examples/notes` 上可用。
---
## 开发原则
NENE2 优化快速、平静的开发。代码库应该易于理解，适用于单个开发人员、团队或 AI 代理，无需隐藏的约定。
- 将领域和用例代码与 HTTP、数据库、模板和 CLI 详细信息解耦。
- 使用 PSR-7 / PSR-15 / PSR-17 作为 HTTP 运行时方向。
- 使用 PSR-11 作为 DI 边界，具有明确的连接线优先。
- 在运行时使用类型化配置对象；保持 `.env` 在加载边界。
- 在添加框架魔术之前，使行为可测试。
- 将 OpenAPI 视为公共 API 契约，并保持 MCP 集成在同一 API 边界后面。
- 保持模板引擎可选；服务器端 HTML 应保持薄且可替换。
- 优先考虑小型、无聊的基元而不是聪明的抽象。
- 在 `docs/` 中记录工作流、路线图和实现决策，而不是仅在聊天中。
## 仓库布局
NENE2 使用单个仓库，Composer 在根目录，PHP 框架代码在 `src/`，测试在 `tests/`，Web 文档根目录在 `public_html/`，可选的 React + TypeScript 前端源代码在 `frontend/`。
```text
.
├── composer.json
├── src/ # NENE2 框架核心
│ ├── Auth/
│ ├── Config/
│ ├── Database/
│ ├── DependencyInjection/
│ ├── Error/
│ ├── Http/
│ ├── Log/
│ ├── Mcp/
│ ├── Middleware/
│ ├── Routing/
│ ├── Validation/
│ ├── View/
│ ├── Example/Note/ # 规范的领域层示例（完整 CRUD）
│ └── Example/Tag/ # 第二个实体示例
├── tests/ # PHPUnit / 架构 / 契约测试
├── config/ # 框架默认配置或示例
├── database/ # 迁移、种子和架构文档
├── templates/ # 原始 PHP 模板和薄服务器端 HTML 源代码
├── public_html/ # Web 文档根目录
│ └── assets/ # 构建的前端资产
├── frontend/ # React/TypeScript/Vite 源代码
│ └── src/
├── docs/
├── LICENSE
└── README.md
```
有关设计细节和放置规则，请参见 `docs/development/project-layout.md`。
## 开发命令
有关从克隆到运行 API 的完整逐步演练，请参见 `docs/development/setup.md`。
NENE2 针对 PHP `>=8.4.1 <9.0`。Docker 是标准开发运行时，因此主机 OS 不需要提供该 PHP 版本。
```bash
docker compose run --rm app composer check
```
Composer 位于仓库根目录，提供第一个后端验证命令：
```bash
composer validate
composer test
composer analyse
composer check
composer test:database
composer test:database:mysql
```
有关运行时和工具的详细信息，请参见 `docs/development/php-runtime.md` 和 `docs/development/docker.md`。
NENE2 的质量基线包括用于后端样式检查的 PHP-CS-Fixer 和用于 React 前端启动器的 npm、ESLint、TypeScript 和 Prettier。前端启动器针对活跃的 Node.js LTS，提交 `package-lock.json`，并通过更新自动化保持依赖项现代化。框架公共 API 应使用 PHPDoc 或 TSDoc，其中注释解释契约或扩展规则。有关详细信息，请参见 `docs/development/quality-tools.md`、`docs/development/frontend-integration.md` 和 `docs/development/documentation-comments.md`。
## 操作指南
262 个任务聚焦的指南，涵盖身份验证、安全、数据库模式、API 设计、后台作业和 100+ 产品功能配方。
**[完整指南索引 →](docs/howto/README.md)**
常见入口点：
- [添加自定义路由](docs/howto/add-custom-route.md)
- [添加数据库支持的端点](docs/howto/add-database-endpoint.md)
- [添加 JWT 身份验证](docs/howto/add-jwt-authentication.md)
- [添加分页](docs/howto/add-pagination.md)
- [添加速率限制](docs/howto/add-rate-limiting.md)
- [部署到生产环境](docs/howto/deploy-production.md)
## 参考实现
**[hideyukiMORI/NENE2-examples](https://github.com/hideyukiMORI/NENE2-examples)** — 125 个使用 `hideyukimori/nene2` 作为 Composer 依赖项构建的现场试验应用程序。每个目录都是一个自包含的可运行 JSON API，对应一个操作指南。
```bash
git clone https://github.com/hideyukiMORI/NENE2-examples.git
cd NENE2-examples/deduplog # 或其他示例
composer install
vendor/bin/phpunit
```
## 交付启动文档
使用这些文档来适配 NENE2 以适用于小型客户端 API：
- 方向：`docs/integrations/llm-delivery-starter.md`
- 客户端项目启动指南：`docs/development/client-project-start.md`
- 端点工作流：`docs/development/endpoint-scaffold.md`
- 本地 MCP 服务器：`docs/integrations/local-mcp-server.md`
- 本地 MCP 客户端配置：`docs/integrations/local-mcp-client-configuration.md`
- MCP 工具策略：`docs/integrations/mcp-tools.md`
- 身份验证边界：`docs/development/authentication-boundary.md`
- 机器客户端烟雾工作流：`docs/development/machine-client-smoke.md`
- 数据库测试策略：`docs/development/test-database-strategy.md`
- 补丁发布策略：`docs/development/release-v0.1.x-policy.md`
**公共现场试验参考（可选）：** [`hideyukiMORI/sakura-exhibition-nene2-field-trial`](https://github.com/hideyukiMORI/sakura-exhibition-nene2-field-trial) — 客户端演示从 **`v0.1.1`** 分叉，具有展览形状的只读 API、OpenAPI、测试、本地 MCP 和现场试验报告。 **与任何真实事件无关；** 参见该仓库的 `README.md`。
## 项目工作流
NENE2 使用 GitHub Issues 作为工作来源，使用本地 Markdown 文件作为项目记忆。
1. 创建或重用一个聚焦的 GitHub Issue。
2. 从 `main` 创建一个 Issue 编号的分支，例如 `docs/1-initial-governance`。
3. 同时更新代码和文档，保持更改小。
4. 使用 Conventional Commits 提交并包含 Issue 编号。
5. 推送、打开 PR、合并后检查并返回本地 `main` 到干净状态。
在更改项目之前，请参见 `docs/CONTRIBUTING.md`、`docs/workflow.md` 和 `AGENTS.md`。
## AI / LLM 集成
NENE2 设计为 AI 可读且可由 AI 代理使用。
- **[`llms.txt`](./llms.txt)** — 用于 LLM 爬虫的机器可读项目摘要（[llmstxt.org](https://llmstxt.org) 标准）。
- **[Smithery](https://smithery.ai/server/hideyukiMORI/nene2)** — NENE2 MCP 服务器列入 Smithery 注册表（[`smithery.yaml`](./smithery.yaml)）。
- **[AGENTS.md](./AGENTS.md)** — AI 代理在该仓库的工作入口。
- **OpenAPI 契约** — `GET /openapi.php` 或 `docs/openapi/openapi.yaml` — LLM 工具使用的权威 API 契约。
- **本地 MCP 服务器** — `composer mcp` 验证 MCP 工具目录；`docker compose run --rm -e NENE2_LOCAL_API_BASE_URL=http://app app php tools/local-mcp-server.php` 启动本地服务器。
- **参考实现** — **[hideyukiMORI/NENE2-examples](https://github.com/hideyukiMORI/NENE2-examples)**：125 个可运行的现场试验应用，涵盖每个主要操作指南（身份验证、安全、队列、社会功能等）。每个应用都是 `composer install && phpunit`-ready。
## 许可证
NENE2 在 MIT 许可证下发布。
## 维护者
NENE2 由 [彩音インターナショナル株式会社 (AYANE International Inc.)](https://ayane.co.jp) 构建和维护，这是 NeNe 产品家族背后的公司。
