# express_serve

**Repository Path**: milocarey/express_serve

## Basic Information

- **Project Name**: express_serve
- **Description**: express5+prisma6.9+winston3搭建的express框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-22
- **Last Updated**: 2025-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Skyline 项目文档

## 项目介绍
这是一个基于 TypeScript 的后端项目，集成了数据库管理、OAuth2 认证、用户注册与登录、密码重置、请求验证、日志记录等功能。项目使用了 Prisma ORM 来管理数据库迁移与模型，并且支持多种 OAuth 提供商，如 GitHub、Google、Twitter 等。

## 技术栈
- TypeScript
- Node.js
- Express
- Prisma ORM
- Redis
- JWT（用于身份验证和令牌管理）
- OAuth2

## 功能特性
- 用户注册和登录（支持密码认证）
- OAuth2 认证（支持 GitHub、Google、Twitter）
- 密码修改和找回功能
- 令牌生成与刷新（使用 JWT）
- 请求速率限制与跨域（CORS）支持
- 全面的错误处理和请求验证
- 数据库连接管理（支持 MySQL、Redis）

## 安装与配置
### 前提条件
- Node.js（建议 v18.x 或更高）
- npm / pnpm
- Redis 服务
- MySQL 数据库

### 安装步骤
1. 克隆项目到本地环境：
   ```bash
   git clone <项目地址>
   ```
2. 安装依赖：
   ```bash
   pnpm install
   ```
3. 配置环境变量：
   - 复制 `.env.example` 为 `.env`，并填写实际配置，例如数据库连接、Redis 地址、JWT 密钥、OAuth 提供商的 clientID 和 clientSecret。
4. 运行 Prisma 数据库迁移：
   ```bash
   npx prisma migrate dev --name init
   ```
5. 启动项目：
   ```bash
   pnpm run dev
   ```

## 使用说明
### API 接口
- **注册**：`POST /api/auth/register`
- **登录**：`POST /api/auth/login`
- **刷新 Token**：`POST /api/auth/refresh-token`
- **登出**：`POST /api/auth/logout`
- **修改密码**：`POST /api/auth/change-password`
- **发送密码重置邮件**：`POST /api/auth/send-password-reset-email`
- **重置密码**：`POST /api/auth/reset-password`
- **获取当前用户信息**：`GET /api/auth/current-user`
- **OAuth 登录**：`GET /api/oauth/:provider`（支持 `github`、`google`、`twitter` �://

### OAuth 流程
1. 前端访问 `/api/oauth/:provider`，后端会返回 OAuth 提供商的授权链接。
2. 用户授权后，OAuth 提供商会将用户重定向到后端的 `/api/oauth/callback`。
3. 后端会处理授权码，获取用户信息，生成 JWT 令牌并返回。

## 目录结构
- **src/** - 项目源代码
  - **app.ts** - Express 应用初始化
  - **index.ts** - 服务启动入口
  - **config/** - 配置相关
    - **database.ts** - 数据库管理（Prisma + Redis）
  - **controller/** - 控制器
    - **authController.ts** - 用户认证相关逻辑
    - **oauthController.ts** - OAuth 认证相关逻辑
  - **routes/** - API 路由
    - **auth.ts** - 用户认证路由
    - **oauth.ts** - OAuth 路由
  - **service/** - 业务逻辑层
    - **authService.ts** - 用户注册、登录、密码管理
    - **oauthService.ts** - OAuth 相关业务逻辑
  - **middleware/** - Express 中间件
    - **auth.ts** - 身份验证中间件
    - **cors.ts** - 跨域资源共享配置
    - **errorHandler.ts** - 错误处理中间件
    - **rateLimit.ts** - 请求频率限制
    - **validateSchema.ts** - 请求数据验证
  - **oauth2/** - OAuth2 提供商实现
    - **base-provider.ts** - 基础 OAuth 提供商类
    - **github-provider.ts** - GitHub OAuth 实现
    - **google-provider.ts** - Google OAuth 实现
    - **twitter-provider.ts** - Twitter OAuth 实现
    - **oauth-factory.ts** - OAuth 提供商工厂
  - **utils/** - 工具类
    - **R.ts** - 响应封装
    - **envParser.ts** - 环境变量解析
    - **logger.ts** - 日志记录器
    - **secret.ts** - 密钥管理

## 数据库与缓存
- **Prisma ORM** 用于管理数据库模型和迁移。
- **Redis** 用于缓存和会话管理，支持缓存用户登录信息和临时数据。

## 日志与调试
- 使用 `winston` 作为日志记录器，支持多种日志格式（JSON、带颜色的控制台输出等）。
- 日志级别支持 `error`、`warn`、`info`、`verbose`、`debug`，可以通过 `.env` 文件配置。

## 安全与验证
- 所有请求都经过数据验证（使用 `validateSchema` 中间件）。
- 密码使用 `bcrypt` 进行加密，支持盐值和加密轮数配置。
- JWT 用于生成访问令牌和刷新令牌，支持自定义过期时间。

## 扩展与维护
- 项目采用模块化设计，易于扩展新的 OAuth 提供商。
- 代码结构清晰，适合企业级开发与长期维护。

## 开发工具
- 使用 `nodemon` 作为热重载工具，方便开发调试。
- 配置了 `tsconfig.json`，支持 TypeScript 编译和类型检查。

## 贡献指南
欢迎提交 PR，请遵循以下流程：
1. Fork 项目
2. 创建新分支 (`git checkout -b feature/your-feature-name`)
3. 提交更改 (`git commit -am 'Add some feature'`)
4. Push 到分支 (`git push origin feature/your-feature-name`)
5. 创建 Pull Request

## 协议
本项目采用 MIT 协议，详细信息请查看 `LICENSE` 文件。

## 联系方式
如需交流或反馈，请通过 Gitee 提交 issue 或联系项目维护者。