Archy

🚀 使用 TypeScript 開發 Archy 服務器

本項目旨在幫助開發者使用 TypeScript 開發 Archy 服務器，詳細介紹了從環境搭建到服務器運行的全流程，以及常見問題的排查方法。

🚀 快速開始

要開始開發 Archy 服務器，需先安裝所需的依賴項。以下是具體的安裝步驟：

npm install typescript ts-node nodemon @types/node @types/express --save-dev

安裝 TypeScript

使用以下命令全局安裝 TypeScript 和類型定義文件：

npm install -g typescript typescript@latest

📦 安裝指南

編寫配置文件

創建並編輯 tsconfig.json 文件，添加以下內容：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "build",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

配置開發環境

在 package.json 中添加以下內容：

{
  "name": "archy-server",
  "version": "1.0.0",
  "scripts": {
    "dev": "ts-node src/index.ts"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "typescript": "^5.0.2",
    "ts-node": "^10.9.2",
    "nodemon": "^3.0.2",
    "@types/node": "^20.10.0",
    "@types/express": "^4.18.1"
  }
}

💻 使用示例

基礎用法

運行開發模式

在開發環境中運行服務器時，可以使用以下命令：

npm run dev

該命令會自動重新加載服務器以響應文件更改。

編譯 TypeScript 項目

使用以下方法運行 TypeScript 編譯器：

使用本地安裝的 TypeScript

npx tsc

要指定 tsconfig.json 文件，可以執行：

npx tsc --project tsconfig.json

要啟用觀察模式（即時重新編譯），請運行：

npx tsc --watch

使用全局安裝的 TypeScript

如果已將 TypeScript 全局安裝，請執行以下命令：

tsc

高級用法

使用 Archy 生成圖表

示例：從文本生成類圖

generate_diagram_from_text({
  "description": "為圖書館系統創建一個包含 Book、Author 和 Library 類的類圖。書籍有標題和 ISBN。作者有姓名並可以編寫多本書。圖書館館藏包含書籍。",
  "language": "zh-CN"
});

示例：從 URL 生成圖表

generate_diagram_from_url({
  "url": "https://example.com",
  "language": "zh-CN"
});

運行服務器

啟動開發服務器：

npm run dev

啟用調試日誌

在 tsconfig.json 中添加以下內容以啟用調試日誌：

{
  "compilerOptions": {
    "traceResolution": true,
    "verbose": true
  }
}

代碼示例

簡單 HTTP 服務器

import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`應用運行在 http://localhost:${port}`);
});

帶有路由的服務器

import express from 'express';
const router = express.Router();

router.get('/api', (req, res) => {
  res.json({ message: 'Hello API' });
});

const app = express();
app.use('/', router);

const port = 3000;
app.listen(port, () => {
  console.log(`應用運行在 http://localhost:${port}`);
});

📚 詳細文檔

常見 TypeScript 編譯選項

• --outDir <directory>：指定輸出目錄。
• --target <ES 版本>：指定 ECMAScript 目標版本（例如 ES2020）。
• --module <模塊系統>：指定模塊系統（例如 NodeNext）。
• --declaration：生成 .d.ts 聲明文件。
• --sourceMap：生成源映射文件以支持調試。

項目結構

• src/：TypeScript 源文件
  • src/index.ts：程序入口點和服務器實現
  • src/server.ts：服務器實現
  • src/generators/：圖表生成邏輯
  • src/utils/：工具函數和輔助函數
• build/：編譯輸出的 JavaScript 文件
• examples/：示例使用腳本
• test/：測試文件

進階功能

配置代理

編輯 tsconfig.json 添加以下內容：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

然後在代碼中使用模塊路徑：

import { generate_diagram_from_text } from '@';

配置 TypeScript 模塊分辨率

編輯 tsconfig.json 添加以下內容：

{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": "."
  }
}

🔧 技術細節

常見問題排查

1. 模塊解析錯誤 確保項目根目錄中存在 tsconfig.json 文件，並且 include 和 exclude 配置正確。
2. 無法啟動服務器 檢查安裝是否成功：

npm list -g typescript ts-node nodemon

總結

通過遵循上述步驟，您可以成功設置和開發一個使用 TypeScript 的 Archy 服務器。