非JS框架原理图创建方法与NX仓库FastAPI原理图搭建技术问询

我来帮你梳理下在NX仓库中为非JS框架（比如你提到的FastAPI）创建原理图的方法和最佳实践——毕竟NX默认更偏向JS/TS生态，非JS的确实需要额外适配，我之前也做过类似的Python服务原理图，给你分享下具体步骤：

先搞懂NX原理图的核心逻辑 #

原理图本质是代码生成模板+变量替换+NX工作区集成，不管是什么语言，核心都是通过定义参数、模板文件和生成逻辑，快速创建符合规范的项目结构。非JS框架的关键是跳过NX默认的JS相关配置，专注于模板文件和自定义生成逻辑。

在NX仓库中启动并创建新原理图的通用最佳实践 #

• 先确保你有NX工作区：如果没有，用npx create-nx-workspace@latest创建，选empty模板即可（不需要预设JS框架）
• 安装原理图开发核心依赖：npm install -D @nrwl/devkit @nrwl/workspace
• 生成基础原理图骨架：运行nx generate @nrwl/workspace:schematics my-fastapi-schematic，这里的my-fastapi-schematic是你的原理图名称
• 进入生成的libs/my-fastapi-schematic目录：这里是原理图的核心开发区，重点关注src/generators/<generator-name>/schema.json（定义用户输入参数）和src/generators/<generator-name>/files（存放FastAPI模板文件）

为FastAPI适配原理图的具体步骤 #

1. 定义原理图输入参数（schema.json） #

修改schema.json，添加FastAPI项目需要的参数，比如项目名称、端口号、是否包含数据库配置等：

{
  "$schema": "http://json-schema.org/schema",
  "id": "FastApiGenerator",
  "title": "Create a FastAPI Service",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the FastAPI service",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    },
    "port": {
      "type": "number",
      "description": "Port for the FastAPI service",
      "default": 8000
    },
    "includeDb": {
      "type": "boolean",
      "description": "Include SQLAlchemy database setup",
      "default": false
    }
  },
  "required": ["name"]
}

2. 创建FastAPI模板文件 #

在files目录下构建你的FastAPI项目模板，用Handlebars语法做变量替换和条件渲染：

• 比如创建{{name}}/main.py模板：

  from fastapi import FastAPI
  
  app = FastAPI(title="{{name}}")
  
  @app.get("/")
  async def root():
      return {"message": "Hello from {{name}}"}
  

• 如果includeDb为true，添加{{name}}/database.py模板（用{% if includeDb %}做条件渲染）：

  {% if includeDb %}
  from sqlalchemy import create_engine
  from sqlalchemy.ext.declarative import declarative_base
  from sqlalchemy.orm import sessionmaker
  
  SQLALCHEMY_DATABASE_URL = "sqlite:///./{{name}}.db"
  
  engine = create_engine(
      SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}
  )
  SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
  
  Base = declarative_base()
  {% endif %}
  

• 还要创建{{name}}/requirements.txt模板，根据参数决定是否添加数据库依赖：

  fastapi==0.104.1
  uvicorn==0.24.0.post1
  {% if includeDb %}
  sqlalchemy==2.0.23
  {% endif %}
  

3. 编写原理图生成逻辑（index.ts） #

NX原理图用TypeScript编写核心逻辑，主要做三件事：复制模板文件、替换变量、更新NX项目配置（让NX识别这个FastAPI项目）：

import { Tree, formatFiles, generateFiles, joinPathFragments } from '@nrwl/devkit';
import { FastApiGeneratorSchema } from './schema';

export default async function (tree: Tree, options: FastApiGeneratorSchema) {
  // 定义模板目录和目标目录
  const templateDir = joinPathFragments(__dirname, './files');
  const targetDir = joinPathFragments('apps', options.name);

  // 生成模板文件并替换变量
  generateFiles(tree, templateDir, targetDir, {
    ...options,
    tmpl: '', // NX默认占位符，必须保留
  });

  // 给FastAPI项目添加NX自定义命令（启动、安装依赖等）
  const projectConfig = {
    root: targetDir,
    projectType: 'application',
    targets: {
      start: {
        executor: '@nrwl/workspace:run-commands',
        options: {
          command: `cd ${targetDir} && uvicorn main:app --reload --port ${options.port}`
        }
      },
      install: {
        executor: '@nrwl/workspace:run-commands',
        options: {
          command: `cd ${targetDir} && pip install -r requirements.txt`
        }
      },
      lint: {
        executor: '@nrwl/workspace:run-commands',
        options: {
          command: `cd ${targetDir} && flake8 .`
        }
      }
    }
  };

  // 写入NX项目配置文件
  tree.write(joinPathFragments(targetDir, 'project.json'), JSON.stringify(projectConfig, null, 2));

  // 格式化文件（主要针对TS/JS，Python可忽略）
  await formatFiles(tree);
}

4. 测试你的原理图 #

在NX工作区根目录运行命令生成FastAPI项目：

nx generate ./libs/my-fastapi-schematic:fast-api my-fastapi-service --port 8001 --includeDb true

然后通过NX命令操作项目：

• 安装依赖：nx run my-fastapi-service:install
• 启动服务：nx run my-fastapi-service:start

非JS框架原理图的额外最佳实践 #

• 隔离依赖：不要把Python依赖加到NX根目录的package.json，每个FastAPI项目自己维护requirements.txt
• 统一命令入口：在project.json里添加常用命令（启动、 lint、测试等），让用户用NX统一管理所有项目操作
• 模板复用：把通用的FastAPI代码（比如中间件、异常处理）抽成可复用的模板片段
• 参数验证：在schema.json里严格定义参数类型和默认值，避免用户输入错误
• 文档说明：在原理图的README.md里写清楚使用方法、支持的参数和后续操作步骤

内容的提问来源于stack exchange，提问作者stiil