Deforge - Universal Edge Function Compiler

标准代码到平台代码的纯粹翻译器 | Pure Translator from Standard to Platform-Specific Code

Deforge 是一个专注的代码编译器，将符合 deislet/spec 标准的 Edge Function 代码翻译为特定平台的可部署代码。

🎯 核心定位

Deforge 只做一件事：翻译代码

输入：符合 deislet/spec 标准的代码库
输出：特定平台（Cloudflare/Deno/Tencent）的可部署代码

✨ 特性

• 纯粹翻译器: 专注于代码转换，不涉及项目管理、开发服务器或部署
• 多平台支持: 一次编写，翻译到 Cloudflare Workers、Deno Deploy、Tencent EdgeOne
• 标准验证: 确保输入代码符合规范，检测平台特定代码
• 自动适配: 自动生成路由器、适配器和配置文件
• 类型安全: 基于 Rust + SWC，保证转换的正确性

📦 架构

deforge/
├── crates/
│   ├── deforge/           # CLI 可执行文件 (validate + build)
│   ├── deforge-core/      # 核心类型定义
│   ├── deforge-parser/    # TypeScript/JavaScript 解析器 (SWC)
│   ├── deforge-compiler/  # 代码验证和转换
│   └── deforge-adapters/  # 平台适配器代码生成

🚀 快速开始

安装

# 克隆项目
git clone https://github.com/deislet/deforge.git
cd deforge

# 构建 (需要 Rust 1.70+)
cargo build --release

# 安装到系统
cargo install --path crates/deforge

使用

1. 验证代码

检查代码是否符合标准，检测平台特定代码：

deforge validate [--strict]

输出示例：

✓ Validating functions/api/users.ts
✓ Validating functions/index.ts
✗ Error in functions/bad.ts:10:5
  Platform-specific code detected: typeof Deno !== 'undefined'

2/3 files passed, 1 error

2. 构建项目

将标准代码翻译为特定平台代码：

# 构建所有平台
deforge build

# 构建特定平台
deforge build --vendor cloudflare
deforge build --vendor deno
deforge build --vendor tencent

# 监视模式（开发时使用）
deforge build --watch

输出目录结构：

dist/
├── cloudflare/
│   ├── index.ts              # 自动生成的路由器
│   ├── wrangler.toml         # Cloudflare 配置
│   ├── src/                  # 转换后的 handlers
│   └── adapters/             # KV/Context 适配器
├── deno/
│   ├── index.ts              # Deno.serve 入口点
│   ├── deno.json             # Deno 配置
│   └── src/                  # 转换后的代码
└── tencent/
    ├── index.ts              # EdgeOne 路由器
    ├── edgeone.toml          # EdgeOne 配置
    └── src/                  # 转换后的代码

📝 输入格式

Deforge 期望符合以下规范的代码：

项目结构

your-project/
├── functions/              # 必须：函数目录
│   ├── index.ts           # 根路由 /
│   ├── api/
│   │   ├── users.ts       # /api/users
│   │   └── [id].ts        # /api/:id （动态路由）
│   └── admin/
│       └── index.ts       # /admin
└── denictl.toml           # 可选：项目配置

Handler 格式

// functions/api/users.ts
import type { Context } from '@denictl/types';

export default async function handler(context: Context): Promise<Response> {
  const { kv } = context.services;
  const userId = context.params.id;

  // 使用统一的 KV 接口 (自动适配各平台)
  const user = await kv.getJSON(`user:${userId}`);

  if (!user) {
    return new Response('User not found', { status: 404 });
  }

  return new Response(JSON.stringify(user), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Context 对象

统一的运行时上下文：

interface Context {
  request: Request;          // 原始 Request 对象
  env: Record<string, string>; // 环境变量
  params: Record<string, string>; // 路由参数
  query: URLSearchParams;    // 查询参数
  services: {                // 统一服务接口
    kv: KVStore;
    database?: Database;
    cache?: Cache;
  };
  log: Logger;               // 结构化日志
  waitUntil: (promise: Promise<any>) => void;
}

🔍 验证规则

Deforge 会检测并禁止以下模式：

❌ 平台类型检测

if (typeof Deno !== 'undefined') { }  // Error!

❌ 直接访问 context.raw

const cfEnv = context.raw.cloudflare.env;  // Error!

❌ 平台特定 API

Deno.env.get('VAR');  // Error! 使用 context.env
process.env.VAR;      // Error! 使用 context.env

✅ 正确的方式

const apiKey = context.env.API_KEY;
const kv = context.services.kv;

🎨 输出示例

输入 (functions/api/hello.ts)

export default async function handler(context: Context): Promise<Response> {
  const name = context.query.get('name') || 'World';
  return new Response(`Hello, ${name}!`);
}

输出 (dist/cloudflare/src/api/hello.ts)

/**
 * Cloudflare Workers Handler
 * Generated from: functions/api/hello.ts
 * Route: /api/hello
 */

import { createContextBuilder } from '../adapters/context-builder';

// Original handler code (保持不变)
export default async function handler(context: Context): Promise<Response> {
  const name = context.query.get('name') || 'World';
  return new Response(`Hello, ${name}!`);
}

// Cloudflare Workers export (自动生成)
export default {
  async fetch(request, env, ctx) {
    const buildContext = createContextBuilder(env, ctx);
    const context = buildContext(request, '/api/hello');
    return await handler(context);
  }
};

输出 (dist/cloudflare/index.ts) - 自动路由器

import handler0 from './src/index';
import handler1 from './src/api/hello';

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (matchRoute(url.pathname, '/')) {
      return handler0.fetch(request, env, ctx);
    }
    if (matchRoute(url.pathname, '/api/hello')) {
      return handler1.fetch(request, env, ctx);
    }

    return new Response('Not Found', { status: 404 });
  }
};

🛠️ 工作流程集成

Deforge 专注于编译，可与其他工具配合使用：

# 1. 验证代码
deforge validate

# 2. 构建目标平台代码
deforge build --vendor cloudflare

# 3. 使用平台工具部署（不是 Deforge 的职责）
cd dist/cloudflare
npx wrangler deploy

🔧 配置文件

可选的 denictl.toml 配置文件：

[project]
name = "my-edge-app"
version = "1.0.0"

[build]
minify = true
source_map = false

[cloudflare]
account_id = "your-account-id"
kv_namespaces = ["KV_STORE"]

[deno]
import_map = "import_map.json"

[tencent]
zone_id = "your-zone-id"

🏗️ 与其他工具的关系

Deforge 不做的事情：

• ❌ 项目初始化 → 使用 create-deislet-app
• ❌ 开发服务器 → 使用 deislet-dev
• ❌ 部署管理 → 使用 wrangler/deployctl 或 deislet-deploy

Deforge 专注于：

• ✅ 代码验证
• ✅ 代码转换
• ✅ 适配器生成
• ✅ 配置文件生成

📊 性能

• 验证速度: ~2s (100 个文件)
• 构建速度: ~5s (100 个handlers)
• 二进制大小: ~15MB (release)
• 内存占用: ~30MB

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md

📄 许可证

Apache-2.0 License

Deforge: Pure. Focused. Efficient.