@fastcar/cli 0.0.7 → 0.1.0

package/skills/fastcar-rpc-microservices/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: fastcar-rpc-microservices
+description: FastCar RPC 与微服务开发指南。Use when working with FastCar framework for: (1) Building RPC servers and clients with @fastcar/rpc, (2) Using WebSocket/SocketIO/MQTT/gRPC for service communication, (3) Setting up microservices architecture (center/connector/chat/web/base), (4) Configuring RPC endpoints, authentication, retry policies, (5) Using protobuf with RPC.
+---
+
+# FastCar RPC & Microservices
+
+FastCar RPC 模块提供基于多种协议（WS、SocketIO、MQTT、gRPC）的远程调用能力，并支持构建 center / connector / chat / web / base 多服务微服务架构。
+
+## RPC 核心概念
+
+### 开启 RPC
+
+```typescript
+import { Application } from "@fastcar/core/annotation";
+import { EnableRPC } from "@fastcar/rpc/annotation";
+
+@Application
+@EnableRPC
+class APP {}
+export default new APP();
+```
+
+### 服务端配置
+
+通过 `ApplicationSetting` 注入 RPC 服务器列表配置类：
+
+```typescript
+import { Application, ApplicationSetting } from "@fastcar/core/annotation";
+import { EnableRPC } from "@fastcar/rpc/annotation";
+import RpcServerList from "./RpcServerList";
+
+@Application
+@EnableRPC
+@ApplicationSetting(RpcServerList)
+class APP {}
+```
+
+`RpcServerList.ts` 示例：
+
+```typescript
+import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
+import { Protocol } from "@fastcar/server";
+import { CodeProtocolEnum } from "@fastcar/rpc/types/CodeProtocolEnum";
+import * as path from "path";
+
+export default {
+  rpc: {
+    list: [
+      { id: "rpc-1", type: SocketEnum.WS, server: { port: 1238 }, serviceType: "rpc" },
+      { id: "rpc-2", type: SocketEnum.SocketIO, server: { port: 1235 }, serviceType: "rpc" },
+      { id: "rpc-3", type: SocketEnum.MQTT, server: { port: 1236, protocol: Protocol.net }, serviceType: "rpc" },
+      {
+        id: "rpc-4",
+        type: SocketEnum.MQTT,
+        server: { port: 1239, protocol: Protocol.https, ssl: { key: "./ssl/server.key", cert: "./ssl/server.crt" } },
+        serviceType: "rpc",
+      },
+      {
+        id: "rpc-5",
+        type: SocketEnum.Grpc,
+        server: { port: 1240, ssl: { ca: path.join(__dirname, "cert/ca.crt"), key: "cert/server.key", cert: "cert/server.crt" } },
+        serviceType: "rpc",
+        codeProtocol: CodeProtocolEnum.PROTOBUF,
+        extra: { checkClientCertificate: true },
+      },
+    ],
+  },
+};
+```
+
+支持的协议类型：
+- `SocketEnum.WS`：WebSocket
+- `SocketEnum.SocketIO`：Socket.IO
+- `SocketEnum.MQTT`：MQTT
+- `SocketEnum.Grpc`：gRPC
+
+### 安全认证
+
+在服务端配置 `secure`：
+
+```typescript
+{
+  id: "rpc-auth",
+  type: SocketEnum.WS,
+  server: { port: 1238 },
+  serviceType: "rpc",
+  secure: { username: "user", password: "123456" },
+}
+```
+
+### RPC 控制器
+
+```typescript
+import { Controller } from "@fastcar/core/annotation";
+import { RPC, RPCMethod, RPCMiddleware } from "@fastcar/rpc/annotation";
+
+@Controller
+@RPC("/hello")
+class HelloController {
+  @RPCMethod
+  async index() {
+    return { message: "Hello RPC" };
+  }
+
+  @RPCMethod("/detail")
+  async detail(data: any) {
+    return { data };
+  }
+}
+```
+
+## RPC 客户端
+
+### 基础客户端
+
+```typescript
+import { RpcClient } from "@fastcar/rpc";
+import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
+import RpcAsyncService from "@fastcar/rpc/service/RpcAsyncService";
+
+class NotifyHandle implements RpcAsyncService {
+  async handleMsg(url: string, data: Object): Promise<void | Object> {
+    console.log("收到服务端消息", url, data);
+    return { url, data: "来自客户端的应答" };
+  }
+}
+
+const client = new RpcClient(
+  {
+    url: "ws://localhost:1238",
+    type: SocketEnum.WS,
+    secure: { username: "user", password: "123456" },
+  },
+  new NotifyHandle()
+);
+
+await client.start();
+const result = await client.request("/hello");
+console.log(result);
+```
+
+### 断线重连与重试策略
+
+```typescript
+const client = new RpcClient(
+  {
+    url: "mqtt://localhost:1236",
+    type: SocketEnum.MQTT,
+    retryCount: 3,        // 错误重试次数
+    retryInterval: 1000,  // 重试间隔（毫秒）
+    timeout: 3000,        // 请求超时（毫秒）
+    maxMsgNum: 10000,     // 最大消息并发数
+    disconnectInterval: 1000, // 断线重连间隔
+  },
+  new NotifyHandle()
+);
+```
+
+### SSL 连接
+
+```typescript
+const client = new RpcClient(
+  {
+    url: "wss://localhost:1239",
+    type: SocketEnum.MQTT,
+    extra: { rejectUnauthorized: false },
+  },
+  new NotifyHandle()
+);
+```
+
+### Protobuf 调用
+
+```typescript
+import { RpcClient } from "@fastcar/rpc";
+import { SocketEnum } from "@fastcar/rpc/constant/SocketEnum";
+import { CodeProtocolEnum } from "@fastcar/rpc/types/CodeProtocolEnum";
+import { ClientRequestStatic } from "@fastcar/rpc/service/rpc/RequestStatic";
+import * as path from "path";
+
+const client = new RpcClient(
+  {
+    url: "local.dev.com:1240",
+    type: SocketEnum.Grpc,
+    codeProtocol: CodeProtocolEnum.PROTOBUF,
+    ssl: {
+      ca: path.join(__dirname, "cert/ca.crt"),
+      key: path.join(__dirname, "cert/client.key"),
+      cert: path.join(__dirname, "cert/client.crt"),
+    },
+    extra: {
+      options: {
+        "grpc.ssl_target_name_override": "example",
+        "grpc.default_authority": "example",
+      },
+    },
+  },
+  new NotifyHandle(),
+  { retryCount: 0 }
+);
+
+client.addProtoBuf({
+  root: {
+    protoPath: path.join(__dirname, "proto/hello.proto"),
+    service: "HelloPBController",
+  },
+});
+
+await client.start();
+
+const res = await ClientRequestStatic<{ message: string }, { code: number; data: string }>({
+  url: "/pbhello",
+  data: { message: "来自客户端的pb调用" },
+  client,
+});
+```
+
+## 微服务架构
+
+FastCar 微服务模板将系统拆分为以下服务模块：
+
+| 模块 | 职责 |
+|------|------|
+| center | 服务中心，提供服务注册与发现 |
+| connector | 连接器服务，处理客户端连接（通常标记 `front: true`） |
+| chat | 聊天服务，处理实时消息 |
+| web | Web 服务，提供 HTTP 接口 |
+| base | 基础服务，提供公共功能 |
+
+### 微服务配置示例
+
+```yaml
+settings:
+  microservices:
+    center:
+      token: "nW0tT4bZ6qM7mF7wD2rT2pR9dT7gK3hZ"
+      servers:
+        - host: "localhost"
+          clusters: 1
+          list:
+            - type: "ws"
+              server: { port: 60000 }
+              timeout: 0
+              connectionLimit: 1
+              disconnectInterval: 1000
+              retry: { retryCount: 3, retryInterval: 3000, timeout: 30000, maxMsgNum: 10000, increase: true }
+    connector:
+      token: "x3TGsWC9uloZu235LA07eAiJ61nQ1A5f"
+      servers:
+        - host: "localhost"
+          clusters: 1
+          list:
+            - front: true
+              type: "ws"
+              server: { port: 60100 }
+    chat:
+      token: "go0kbkNM3wQ4e2Vgo0kbkNM3wQ4e2V"
+      servers:
+        - host: "localhost"
+          clusters: 1
+          list:
+            - type: "ws"
+              server: { port: 60200 }
+    web:
+      token: "go0kbkNM3wQ4e2Vgo0kbkNM3wQ4e2V"
+      koa:
+        koaBodyParser:
+          enableTypes: ["json", "form", "text"]
+      servers:
+        - host: "localhost"
+          clusters: 1
+          list:
+            - type: "http"
+              server: { port: 8080 }
+            - type: "ws"
+              server: { port: 60300 }
+```
+
+### 配置项说明
+
+- `token`：服务间通信鉴权令牌
+- `clusters`：集群实例数，`serviceId` 和端口号自动递增
+- `front: true`：标记为面向客户端的前置节点
+- `timeout`：连接超时（毫秒），`0` 表示永不超时
+- `connectionLimit`：最大连接数限制
+- `disconnectInterval`：断线重连间隔
+- `retry`：重试策略（`retryCount`, `retryInterval`, `timeout`, `maxMsgNum`, `increase`）
+
+## 完整模块列表
+
+| 模块 | 安装命令 | 用途 |
+|------|----------|------|
+| @fastcar/rpc | `npm i @fastcar/rpc @fastcar/server` | RPC 通信 |
+| @fastcar/server | `npm i @fastcar/server` | 服务器统一管理 |
+
+## 快速开始
+
+```bash
+# RPC 项目
+mkdir my-rpc-app && cd my-rpc-app
+fastcar-cli init rpc
+npm install
+npm run debug
+
+# Microservices 项目
+mkdir my-ms-app && cd my-ms-app
+fastcar-cli init microservices
+npm install
+npm run start-node
+```

package/skills/fastcar-serverless/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: fastcar-serverless
+description: FastCar Serverless 开发指南。Use when working with FastCar framework for: (1) Building serverless functions for Aliyun FC, Tencent SCF, or AWS Lambda, (2) Using @ServerlessApp, @Handler, @HttpTrigger, @TimerTrigger, @EventTrigger decorators, (3) Local development and debugging of serverless applications, (4) Integrating Koa middleware in serverless environments.
+---
+
+# FastCar Serverless
+
+FastCar Serverless 框架支持将 FastCar 应用部署到阿里云函数计算（FC）、腾讯云云函数（SCF）和 AWS Lambda，同时提供本地开发调试能力。
+
+## 核心装饰器
+
+### @ServerlessApp
+
+定义 Serverless 应用入口，可显式声明依赖组件和初始化逻辑。
+
+```typescript
+import { ServerlessApp, Service, Handler, HttpTrigger, TimerTrigger, EventTrigger } from "@fastcar/serverless";
+
+@Service
+class OrderService {
+  async createOrder(data: any) {
+    return { orderId: Date.now(), ...data };
+  }
+}
+
+@ServerlessApp({
+  name: "order-service",
+  version: "1.0.0",
+  components: [OrderService],
+  init: async (app) => {
+    console.log("Order service initializing...");
+  },
+})
+class OrderApp {
+  @HttpTrigger({ path: "/orders", method: "POST" })
+  @Handler()
+  async createOrder(event: any, context: any) {
+    const orderService = (this as any).app.getFastCarApp().getComponentByName("OrderService") as OrderService;
+    const order = await orderService.createOrder(event.body);
+    return {
+      statusCode: 200,
+      headers: { "Content-Type": "application/json" },
+      body: { success: true, data: order },
+    };
+  }
+
+  @HttpTrigger({ path: "/orders/:id", method: "GET" })
+  @Handler()
+  async getOrder(event: any, context: any) {
+    return {
+      statusCode: 200,
+      body: { orderId: event.params?.id },
+    };
+  }
+
+  @TimerTrigger({ cron: "0 0 * * * *" })
+  @Handler()
+  async hourlyReport(event: any, context: any) {
+    console.log(`[${context.requestId}] Generating hourly report`);
+    return { success: true };
+  }
+
+  @EventTrigger({ eventSource: "oss" })
+  @Handler()
+  async handleFileUpload(event: any, context: any) {
+    console.log(`[${context.requestId}] Processing file upload event`);
+    return { success: true };
+  }
+}
+
+const orderApp = new OrderApp();
+```
+
+### 触发器类型
+
+| 装饰器 | 用途 | 示例 |
+|--------|------|------|
+| `@HttpTrigger` | HTTP API 触发 | `@HttpTrigger({ path: "/api", method: "GET" })` |
+| `@TimerTrigger` | 定时触发 | `@TimerTrigger({ cron: "0 0 * * * *" })` |
+| `@EventTrigger` | 事件触发（OSS/COS 上传等） | `@EventTrigger({ eventSource: "oss" })` |
+| `@Handler` | 标记处理方法 | `@Handler()` |
+
+## 本地开发调试
+
+使用 `ServerlessApplication` + `startLocalDev` 在本地启动开发服务器：
+
+```typescript
+import {
+  ServerlessApplication,
+  ServerlessContext,
+  HttpTrigger,
+  Handler,
+  Service,
+  Controller,
+  Autowired,
+  LoggerMiddleware,
+  CorsMiddleware,
+  ErrorMiddleware,
+} from "@fastcar/serverless";
+import { startLocalDev } from "@fastcar/serverless/local";
+
+@Service
+class UserService {
+  private users = [
+    { id: "1", name: "张三" },
+    { id: "2", name: "李四" },
+  ];
+  findAll() { return this.users; }
+  findById(id: string) { return this.users.find(u => u.id === id); }
+  create(user: any) {
+    const newUser = { id: String(Date.now()), ...user };
+    this.users.push(newUser);
+    return newUser;
+  }
+}
+
+@Controller
+class UserController {
+  @Autowired
+  private userService!: UserService;
+
+  @HttpTrigger({ path: "/users", method: "GET" })
+  @Handler()
+  async listUsers(ctx: ServerlessContext) {
+    ctx.json({ code: 0, data: this.userService.findAll(), requestId: ctx.requestId });
+  }
+
+  @HttpTrigger({ path: "/users/:id", method: "GET" })
+  @Handler()
+  async getUser(ctx: ServerlessContext) {
+    const user = this.userService.findById(ctx.params.id);
+    if (!user) ctx.throw(404, "User not found");
+    ctx.json({ code: 0, data: user });
+  }
+
+  @HttpTrigger({ path: "/users", method: "POST" })
+  @Handler()
+  async createUser(ctx: ServerlessContext) {
+    const user = this.userService.create(ctx.bodyData);
+    ctx.status = 201;
+    ctx.json({ code: 0, data: user });
+  }
+}
+
+async function main() {
+  const app = new ServerlessApplication();
+  app.register(UserController, UserService);
+  app.use(ErrorMiddleware({ includeStack: true }));
+  app.use(LoggerMiddleware({ logQuery: true }));
+  app.use(CorsMiddleware({ origin: "*" }));
+
+  await startLocalDev(app, {
+    port: 3000,
+    host: "127.0.0.1",
+    onStart: () => {
+      console.log("Serverless local dev server running at http://127.0.0.1:3000");
+    },
+  });
+}
+
+main().catch(console.error);
+```
+
+## 云平台适配器
+
+### 阿里云 FC
+
+```typescript
+import { createFCAdapter } from "@fastcar/serverless";
+export const handler = createFCAdapter((orderApp as any).app);
+```
+
+### 腾讯云 SCF
+
+```typescript
+import { createSCFAdapter } from "@fastcar/serverless";
+export const main_handler = createSCFAdapter((orderApp as any).app);
+```
+
+### AWS Lambda
+
+```typescript
+import { createLambdaAdapter } from "@fastcar/serverless";
+export const handler = createLambdaAdapter((orderApp as any).app);
+```
+
+## 常用中间件
+
+```typescript
+import { LoggerMiddleware, CorsMiddleware, ErrorMiddleware } from "@fastcar/serverless";
+
+app.use(ErrorMiddleware({ includeStack: true }));
+app.use(LoggerMiddleware({ logQuery: true }));
+app.use(CorsMiddleware({ origin: "*" }));
+```
+
+## 完整模块列表
+
+| 模块 | 安装命令 | 用途 |
+|------|----------|------|
+| @fastcar/serverless | `npm i @fastcar/serverless` | Serverless 框架 |
+
+## 快速开始
+
+```bash
+# 安装依赖
+npm i @fastcar/core @fastcar/serverless
+
+# 本地开发
+npx ts-node serverless-app.ts
+```