Skip to content

README.md

Latest commit

 

History

History
198 lines (130 loc) · 5.83 KB

README.md

File metadata and controls

198 lines (130 loc) · 5.83 KB

NEXUS API Management

NEXUS 是一个包含「接口管理 UI + 后端 API + 前端代码生成器」的完整工程：

  • 后端维护 Service / API / 参数树与版本迭代（可选 Owner 迭代审批 与 变更审计）；
  • 前端提供可视化管理界面（含待审列表 /approvals）；
  • CLI 可在任意前端项目中生成 TypeScript 调用代码（可注入 axios/fetch 等 request）。

产品说明（PRD）已整理到 docs/PRD.md。

目录结构

快速开始（本机开发）

1) 启动后端（BACKEND-NEXUS）

依赖：Python（见 BACKEND-NEXUS/pyproject.toml 里的 requires-python）、uv、PostgreSQL（以及按需的 Redis）。

  1. 安装依赖（首次运行）：
cd BACKEND-NEXUS
uv sync
  1. 准备环境变量（复制 BACKEND-NEXUS/.env.example 为 BACKEND-NEXUS/.env，字段说明见 BACKEND-NEXUS/README.md）。
  • 默认端口：PORT=1024

  1. 初始化数据库（首次搭建）：

    1. 安装并启动 PostgreSQL

    2. 创建数据库用户与库（示例以 .env.example 默认值为准：用户/库名都是 cam）：

    -- 进入 psql（以超级用户 postgres 为例）
-- psql -U postgres

CREATE USER cam WITH PASSWORD 'YOUR_PASSWORD';
CREATE DATABASE cam OWNER cam;
GRANT ALL PRIVILEGES ON DATABASE cam TO cam;

  1. 在 BACKEND-NEXUS/.env.example 的基础上填写 DATABASE_* 与 DATABASE_URI

  2. 创建表结构（首次建表建议用 create_all）：

cd BACKEND-NEXUS
uv run python -m database.init_db
  1. 数据库迁移（模型变更时）：

目前仓库提供了迁移脚本（见 BACKEND-NEXUS/database/db-migrate.ps1），用于在你修改 database/models.py 后生成/执行迁移。 若你的本地环境已配置好 Alembic（alembic.ini / 迁移目录等），可直接运行：

cd BACKEND-NEXUS
./database/db-migrate.ps1
  1. 启动开发环境（热重载）：
cd BACKEND-NEXUS
./run-dev.ps1

也可以在仓库根目录直接执行 run-dev.ps1，一次同时启动前后端。

后端默认监听：http://127.0.0.1:1024（根路径 / 返回 OK）。

2) 启动前端（FRONTEND-NEXUS）

前端默认端口为 9000，并且默认会请求本机后端 http://127.0.0.1:1024。

  1. 安装依赖：
cd FRONTEND-NEXUS
npm install
# 或 pnpm install
  1. 启动：
npm run dev
# 或 pnpm dev

前端开发环境变量已在 FRONTEND-NEXUS/.env.development 中给出：

  • VITE_API_BASE_URL=http://127.0.0.1:1024
  • VITE_FE_PORT=9000

注意：后端 CORS 白名单默认允许 http://localhost:9000 与 http://127.0.0.1:9000。

3) 使用代码生成器（nexus-api-codegen）

生成器是一个 CLI：你在哪个目录执行 nexus ...，就会在那个目录生成/读取 nexus.config.json，并把代码输出到该配置的 outDir。

在本机安装/构建（一次性）

cd nexus-api-codegen
npm install
npm run build

让 nexus 命令全局可用（推荐本机用）

在 nexus-api-codegen 目录执行：

npm link

之后你在任意项目目录都可以直接用：nexus -h / nexus --help。

方式 2：装到某个项目里（更可复现/不污染全局）

  1. 在生成器目录打包：
cd e:\API-Management\nexus-api-codegen
npm run build
npm pack

会生成一个类似 nexus-api-codegen-1.7.0.tgz 的文件。

  1. 在另一个前端项目根目录安装该 tgz（建议作为开发依赖）：
cd <你的前端项目根目录>
npm i -D <生成的tgz文件路径>
  1. 用 npx 调用：
  npx nexus init
  npx nexus update
也可以用 `npx nexus -h` / `npx nexus --help` 查看全部命令与参数。

在另一个独立前端项目里生成代码

在你的“目标前端项目根目录”执行：

nexus login
nexus init
nexus list     # 列出所有服务
nexus add <service_name>:<service_uuid>@latest
nexus update

生成器会默认输出到 nexus.config.json 里的 outDir（默认 src/nexus-auto-generate）。

注意：nexus update 会递归删除并重建 outDir，请确保该目录仅用于生成产物。

生成器请求地址

当前生成器请求后端的 baseURL 在 nexus-api-codegen/src/request/index.ts 中配置；本仓库默认按本机后端 http://127.0.0.1:1024 使用。

常用脚本

后端（Windows PowerShell）：

  • 开发：BACKEND-NEXUS/run-dev.ps1
  • 生产：BACKEND-NEXUS/run-prod.ps1
  • 数据库迁移：BACKEND-NEXUS/database/db-migrate.ps1

前端：

  • 开发：cd FRONTEND-NEXUS && pnpm dev
  • 构建：cd FRONTEND-NEXUS && pnpm build

生成器：

  • 构建：cd nexus-api-codegen && npm run build

更多文档