# thinkNodeTs

**Repository Path**: net561/think-node-ts

## Basic Information

- **Project Name**: thinkNodeTs
- **Description**: think-node 仿thinkphp8 开发框架设计思路实现 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThinkNode TS

> 仿 ThinkPHP 8 架构的 Node.js 后端框架 — **TypeScript Edition**

纯 TypeScript 实现，支持类型检查、IDE 智能提示、泛型 ORM。默认输出 ESM 编译产物，也可以直接用 tsx 运行源码。

---

## 特性一览

- 🧱 **IoC / Facade**：容器 + 门面（Proxy）
- 🛣 **Route**：REST 路由、资源路由、路由组、命名路由、中间件
- 🛡 **洋葱模型 Middleware**：全局、路由组、路由级三种
- 💾 **ORM（Model / QueryBuilder）**：链式查询、访问器 / 修改器、时间戳
- 🗂 **Database**：MySQL（mysql2）+ 可扩展 Adapter
- ⚙ **Config**：`config/*.ts` 自动加载，支持 `config('key.sub', default)`
- ✅ **Validate**：30+ 内置规则 + 自定义规则
- 📡 **Event**：事件 / 一次性 / 移除监听
- 📜 **Log**：多级别日志 + 自动写文件
- ⌨ **CLI**：`think serve` / `make:controller` / `make:model` / `route:list`
- 🪟 **跨平台**：统一处理 Windows 路径，动态 import 安全

---

## 环境要求

| 工具   | 版本建议           |
| ------ | ------------------ |
| Node   | >= 18              |
| pnpm   | >= 8（也可用 npm） |
| TypeScript | >= 5.4（dev） |
| tsx | >= 4（dev） |

> `mysql2` 是可选依赖，只有在需要数据库时才安装。

---

## 安装（作为项目依赖）

```bash
# 1) 将仓库放到项目的 lib/think-node/ 目录（或直接用源码路径）
mkdir -p lib/think-node
git clone <仓库地址> lib/think-node

# 2) 在自己的 package.json 中声明依赖：
#    "dependencies": { "think-node-ts": "file:./lib/think-node" }
#    也可以直接发布到 npm。

# 3) 安装依赖
pnpm install

# 4) 构建框架（会产出 dist/ 目录）
cd lib/think-node
pnpm build    # 或 npm run build
```

也可以直接在本仓库目录里开发：

```bash
pnpm install
pnpm build
```

---

## 脚本说明（package.json）

本仓库暴露的脚本：

```bash
pnpm build          # tsc 编译，产出 dist/（可被外部项目 import 的 ESM + 类型）
pnpm clean          # 删除 dist/
pnpm typecheck      # tsc --noEmit，类型检查
# 运行示例（需先创建 example 目录，见下）
pnpm dev            # node --import tsx --watch example/server.ts
pnpm start          # node --import tsx example/server.ts
```

---

## 快速开始：运行示例

仓库没有内置示例，建议在自己的项目里搭建。最小目录结构：

```text
my-app/
├── app/
│   ├── controller/
│   │   ├── IndexController.ts
│   │   └── UserController.ts
│   ├── middleware/
│   │   └── Cors.ts
│   └── model/
│       └── User.ts
├── config/
│   ├── app.ts
│   ├── database.ts
│   ├── log.ts
│   └── middleware.ts
├── route/
│   └── route.ts
├── server.ts
├── package.json
└── tsconfig.json
```

`server.ts` 示例：

```ts
import { join, dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import { ThinkNode } from 'think-node-ts'

const rootPath = dirname(fileURLToPath(import.meta.url))

const app = await ThinkNode(rootPath)
const port = app.config<number>('app.port', 3000)

app.listen(port, () => {
  console.log(`[ThinkNode] server running at http://127.0.0.1:${port}`)
})
```

`config/app.ts`：

```ts
export default {
  name: 'My App',
  debug: true,
  port: 3000,
  timezone: 'Asia/Shanghai',
  default_controller: 'Index',
  default_action: 'index',
}
```

`route/route.ts`：

```ts
import type { Router } from 'think-node-ts'

export default function (router: Router): void {
  router.get('/', 'IndexController@index')
  router.resource('/user', 'UserController')
}
```

`app/controller/IndexController.ts`：

```ts
import { BaseController } from 'think-node-ts'

export default class IndexController extends BaseController {
  async index() {
    return this.success({ hello: 'world' })
  }
}
```

然后启动：

```bash
node --import tsx server.ts
# 或：
pnpm dev
```

---

## 对外 API

框架提供两种导入风格：**从编译产物 import**（推荐用于生产），或 **从 TypeScript 源码 import**（推荐在 tsx / Vite 工具链中直接使用）。

### 1）通过编译产物 import

构建后会生成 `dist/`，`package.json` 的 `main` / `exports` / `types` 都指向它。

```ts
// 入口类 / 常用工具
import {
  App,
  Container,
  BaseController,
  Model,
  Router,
  Validate,
  Cli,
  ThinkNode,
  createApp,
} from 'think-node-ts'

// 常用 Facade / helpers
import { app, config, db, log, event, validate, ipc } from 'think-node-ts'

// 类型
import type {
  ApiResponse,
  AppConfig,
  DatabaseConfig,
  MiddlewareContext,
  MiddlewareHandler,
  RouteHandler,
  ControllerAction,
  RouteDefinition,
  ValidationRule,
  ValidationResult,
  ModelAttributes,
  Binding,
  EventListener,
  IServiceProvider,
} from 'think-node-ts'
```

CLI 入口（bin）：

```bash
npx think <command>
# 如：npx think route:list
```

### 2）直接 import TS 源码（tsx / Vite / electron-vite）

```ts
import App from 'think-node-ts/src/core/App'
import BaseController from 'think-node-ts/src/controller/BaseController'
import Model from 'think-node-ts/src/model/Model'
import Db from 'think-node-ts/src/facade/Db'
import { pathToFileURL } from 'think-node-ts/src/support/pathToFileURL'
```

---

## 架构总览

| 模块         | 路径                             | 说明                      |
| ------------ | -------------------------------- | ------------------------- |
| Container    | src/core/Container.ts            | IoC 容器                  |
| App          | src/core/App.ts                  | 应用核心（异步初始化）    |
| ServiceProvider | src/core/ServiceProvider.ts   | 服务提供者基类            |
| Facade       | src/facade/Facade.ts             | 门面基类（Proxy）         |
| Router       | src/route/Router.ts              | 路由器                    |
| Route        | src/route/Route.ts               | 单条路由（编译后匹配）    |
| RouteGroup   | src/route/RouteGroup.ts          | 路由组                    |
| Middleware   | src/http/Middleware.ts           | 洋葱模型中间件            |
| Kernel       | src/http/Kernel.ts               | HTTP 内核                |
| Request      | src/http/Request.ts              | HTTP 请求                |
| Response     | src/http/Response.ts             | HTTP 响应                |
| BaseController | src/controller/BaseController.ts | 控制器基类               |
| Model        | src/model/Model.ts               | ORM 模型                 |
| QueryBuilder | src/model/QueryBuilder.ts        | 查询构造器               |
| Database     | src/db/Database.ts               | 数据库管理器             |
| MysqlAdapter | src/db/MysqlAdapter.ts           | MySQL 适配器             |
| Config       | src/config/Config.ts             | 配置管理（异步）         |
| Validate     | src/validate/Validate.ts         | 30+ 验证规则             |
| Event        | src/event/Event.ts               | 事件系统                 |
| Log          | src/log/Log.ts                   | 日志                     |
| Cli          | src/console/Cli.ts               | CLI 工具                 |
| helpers      | src/support/helpers.ts           | 辅助函数（Facade 访问器）|
| pathToFileURL | src/support/pathToFileURL.ts    | 跨平台动态 import 路径工具|
| 类型定义    | types.ts                         | 对外类型集中导出         |

---

## 与 ESM / TypeScript 版本的差异

| 特性                 | TypeScript（源码）                        | ESM 编译产物                         |
| -------------------- | ----------------------------------------- | ------------------------------------ |
| 文件扩展名           | `.ts`                                     | `.js`                               |
| 类型系统             | 完整                                      | `.d.ts` 附带                         |
| 运行方式             | `tsx file.ts` / `node --import tsx file.ts` | `node dist/file.js`                |
| ORM 泛型             | `Model.query<T>()`                        | 同上                                 |
| 导入路径             | `.../src/controller/BaseController`       | `think-node-ts`（主入口）            |

---

## 在 Electron + Vite 项目中集成

```json
{
  "dependencies": {
    "think-node-ts": "file:./lib/think-node"
  }
}
```

主进程里启动服务：

```ts
import { fileURLToPath } from 'node:url'
import { dirname, join } from 'node:path'
import { ThinkNode } from 'think-node-ts'

const __dirname = dirname(fileURLToPath(import.meta.url))

const app = await ThinkNode(join(__dirname, '..'))
const port = app.config<number>('app.port', 3000)

app.listen(port, () => {
  console.log(`[ThinkNode] backend running at http://127.0.0.1:${port}`)
})
```

---

## 发布 / 开发

```bash
# 发布前自动构建
npm run prepublishOnly

# 或手动
npm run clean
npm run build
npm publish
```

---

## License

MIT