# ts_backend

**Repository Path**: earsay/ts_backend

## Basic Information

- **Project Name**: ts_backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ts-backend

这是一个基于 Express + TypeScript 的后端项目基础模板。

## 目录结构

```text
ts-backend/
  src/
    routes/
      health.route.ts
    app.ts
    server.ts
  .env.example
  .gitignore
  package.json
  package-lock.json
  tsconfig.json
```

## 文件说明

### package.json

项目配置文件，用来记录项目基础信息、依赖包和常用 npm 命令。

常用命令：

```bash
npm run dev
npm run build
npm start
npm run typecheck
```

说明：

- `npm run dev`：开发模式启动项目，代码修改后自动重启。
- `npm run build`：将 TypeScript 编译为 JavaScript。
- `npm start`：运行编译后的生产代码。
- `npm run typecheck`：只做 TypeScript 类型检查，不生成文件。

### package-lock.json

npm 自动生成的依赖锁定文件，用来固定依赖版本，保证不同环境安装出来的依赖尽量一致。

一般不需要手动修改。

### node_modules/

依赖安装目录，里面存放 Express、TypeScript 等第三方包。

该目录可以通过 `npm install` 重新生成，因此不需要提交到 Git。

### tsconfig.json

TypeScript 配置文件，用来指定源码目录、编译输出目录、模块规则和类型检查规则。

当前主要配置：

- `rootDir: "src"`：源码目录。
- `outDir: "dist"`：编译输出目录。
- `strict: true`：开启严格类型检查。
- `module: "NodeNext"`：使用 Node.js ESM 模块规则。

### .env.example

环境变量示例文件。

当前内容：

```env
PORT=3000
NODE_ENV=development
```

实际开发时可以复制一份 `.env`：

```bash
copy .env.example .env
```

### .gitignore

Git 忽略配置文件，用来声明哪些文件或目录不需要提交。

当前忽略内容：

- `node_modules`
- `dist`
- `.env`
- `npm-debug.log*`

### src/app.ts

Express 应用主体文件，负责创建 app、注册中间件和路由。

当前包含：

- `cors()`：允许跨域请求。
- `express.json()`：支持解析 JSON 请求体。
- `/api/health`：注册健康检查路由。

### src/server.ts

项目启动入口文件，负责读取端口并启动 HTTP 服务。

默认端口为 `3000`。

启动后服务地址：

```text
http://localhost:3000
```

### src/routes/health.route.ts

健康检查接口路由。

接口地址：

```http
GET /api/health
```

返回示例：

```json
{
  "status": "ok",
  "timestamp": "2026-05-12T07:26:40.480Z"
}
```

## 如何运行

### 1. 安装依赖

```bash
npm install
```

### 2. 配置 MySQL

复制环境变量文件：

```bash
copy .env.example .env
```

修改 `.env` 中的数据库连接：

```env
DATABASE_URL="mysql://root:password@localhost:3306/ts_backend"
```

格式说明：

```text
mysql://用户名:密码@主机:端口/数据库名
```

### 3. 生成 Prisma Client

```bash
npm run prisma:generate
```

### 4. 创建数据库表

先确保 MySQL 中已经存在数据库：

```sql
CREATE DATABASE ts_backend;
```

然后执行迁移：

```bash
npm run prisma:migrate
```

### 5. 开发模式启动

```bash
npm run dev
```

访问：

```text
http://localhost:3000/api/health
```

## 用户接口示例

### 创建用户

```http
POST /api/users
Content-Type: application/json
```

请求体：

```json
{
  "name": "Tom",
  "email": "tom@example.com"
}
```

### 查询用户列表

```http
GET /api/users
```

### 根据 ID 查询用户

```http
GET /api/users/1
```

### 构建项目

```bash
npm run build
```

### 运行生产代码

```bash
npm start
```

## 后续推荐结构

项目变大后，可以继续拆分为更标准的后端分层结构：

```text
src/
  config/
  controllers/
  middlewares/
  routes/
  services/
  utils/
  app.ts
  server.ts
```

示例用户模块：

```text
src/routes/user.route.ts
src/controllers/user.controller.ts
src/services/user.service.ts
```

这种结构更利于维护、测试和扩展。