命令参考

本页面收录了在 SOLO 工作模式和本文档项目中常用的命令。

1. 文档相关命令

这些命令通过 pnpm 执行，用于管理本文档站点。

命令	描述
pnpm docs:dev	启动 VitePress 开发服务器，用于实时预览文档更改。
pnpm docs:build	构建静态文档网站，生成的文件位于 docs/.vitepress/dist。
pnpm docs:preview	在本地预览构建后的静态网站。

2. 代码生成命令

这些命令是 API-First 流程的核心，用于根据 openapi.yaml 规范生成代码。

a. OpenAPI Generator

我们使用 openapi-generator-cli 工具。基本用法如下：

openapi-generator-cli generate -i <输入文件> -g <生成器名称> -o <输出目录> [附加选项]

• -i: 指定输入的 OpenAPI 规范文件（例如 openapi.yaml）。
• -g: 指定要使用的语言/框架生成器（例如 spring, typescript-fetch, python-fastapi）。
• -o: 指定生成代码的输出目录。

b. 项目脚本示例

在 package.json 中，我们通常会封装更具体的生成命令。

生成 Java Spring Boot 服务端桩代码:

pnpm generate:server:java

实际脚本可能为: openapi-generator-cli generate -i openapi.yaml -g spring -o generated/java-server --api-package com.example.api --model-package com.example.model

生成 TypeScript Fetch 客户端代码:

pnpm generate:client:ts

实际脚本可能为: openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o generated/ts-client

3. 项目管理与生成

我们提供了一些脚本来简化项目的创建和管理。

创建新项目:

node scripts/project-generator.js --type <项目类型> --name <项目名称>

• --type: 项目类型，例如 java-spring, python-fastapi。
• --name: 新项目的目录名称。

示例:

# 创建一个名为 my-new-service 的 Java Spring Boot 项目
node scripts/project-generator.js --type java-spring --name my-new-service

4. 测试相关命令

运行单元/集成测试 (以 Maven 为例):

# 在 Java 项目目录下运行
./mvnw test

运行契约测试 (使用 Schemathesis):

# 确保应用正在运行
st run --checks all openapi.yaml --base-url http://localhost:8080

5. 常用 Git 命令

命令	描述
git status	查看工作区文件状态。
git add .	将所有更改添加到暂存区。
git commit -m "feat: 添加新功能"	提交暂存区的更改。
git pull --rebase	拉取远程更新并变基。
git push	推送本地提交到远程仓库。