# snail-job-node

**Repository Path**: opensnail/snail-job-node

## Basic Information

- **Project Name**: snail-job-node
- **Description**: snail job node 客户端
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-11
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: task-schedule

**Tags**: None

## README

# snail-job-node

SnailJob 的 Node.js + TypeScript 客户端实现。

## 简介

这是 SnailJob Python 客户端的 Node.js + TypeScript 版本，提供了与 Python 版本相同的功能，包括：

- 定时任务调度
- Map/MapReduce 任务
- 工作流任务
- 静态分片任务
- 实时日志上报
- gRPC 通信

## 注意事项

1. 需要 Node.js 23+ 版本
2. 确保 SnailJob 服务器已启动并可以访问
3. 配置文件 `.env` 需要正确设置

## 安装

```bash
pnpm install
```

## 配置

> 客户端的配置需要注意
>
> 1: 客户端和服务端的配置均在 .env 处
>
> 2: 首先从 `Snail Job` 后台的组管理页面新增一个组
>
> 3: 从该组找到客户端需要的配置参数后填写到 .env 里

```env
# 服务器配置
SNAIL_SERVER_HOST=127.0.0.1
SNAIL_SERVER_PORT=服务端 grpc 端口

# 客户端配置
SNAIL_HOST_IP=127.0.0.1
SNAIL_HOST_PORT=可自定义端口
SNAIL_NAMESPACE=你的组id
SNAIL_GROUP_NAME=你的组名称
SNAIL_TOKEN=你的token
SNAIL_LABELS=env:dev,app:demo
```

## 使用示例

### 创建一个执行器

- `sj.job("执行器名称")` 该执行器名称可自定义

```ts
import * as sj from "../src";
import { JobArgs, MapArgs, ReduceArgs, MergeReduceArgs } from "../src/args";
import { spawn, exec } from "child_process";

export const testmain = sj.job("testmainfun")(async function (
  args: JobArgs
): Promise<sj.ExecuteResult> {
  // 输出本地日志
  // sj.SnailLog.LOCAL.info("这条日志只会在本地显示");
  // 上报日志到服务端的方法
  sj.SnailLog.REMOTE.info("我是上报日志的方法");
  try {
    // 你的业务代码...

    // 向服务端推送成功状态
    return sj.createSuccessExecuteResult();
  } catch (err) {
    // 向服务端推送失败状态
    return sj.createFailureExecuteResult();
  }
});
```

### 创建一个执行器

- 推送执行器到服务端上

```ts
// example/main.ts

// 寻找到main方法
async function main() {
  // 把下方代码复制到main里,参数则是 执行器名称
  // 推荐: 服务端用到什么执行器则推送什么
  ExecutorManager.register(demoJob.testmainfun);
}
```

## 运行

- 暂时没有打包方式😑

```bash
pnpm run dev
```

### 服务后台运行

- 服务器拉取整个库,上传自己的脚本代码到 `example` 处

- 拉取依赖 `pnpm i`

- 后台运行 

    ```cmd
    nohup pnpm run dev > app.log 2>&1 &
    ```

## 项目结构

```
JOB_Node/
├── src/
│   ├── config.ts          # 配置管理
│   ├── exec.ts            # 执行管理器
│   ├── main.ts            # 客户端主函数
│   ├── args.ts            # 参数构建
│   ├── ctx.ts             # 上下文管理
│   ├── deco.ts            # 装饰器
│   ├── log.ts             # 日志
│   ├── rpc.ts             # RPC 通信
│   ├── utils.ts           # 工具函数
│   ├── schemas/           # 数据模型
│   ├── grpc/              # gRPC 相关
│   └── builtins/           # 内置执行器
├── example/               # 示例代码
└── dist/                  # 编译输出
```