# pyBaseProject

**Repository Path**: code_tjf/py-base-project

## Basic Information

- **Project Name**: pyBaseProject
- **Description**: 基础py项目的搭建
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flask 企业级接口服务

## 项目介绍

这是一个基于 Flask + Uvicorn + Swagger 的企业级接口服务，支持多环境配置、HTTPS、Token 鉴权、API 版本控制和全局异常捕获等功能。

### 主要功能

- **多环境配置**：支持开发、测试、生产环境的配置管理
- **HTTPS 支持**：内置 SSL 证书配置
- **API 版本控制**：支持 v1 和 v2 版本的接口管理
- **Swagger 接口文档**：自动生成接口文档，方便查看和测试
- **鉴权机制**：支持 Token 鉴权和 API Key 鉴权
- **全局异常捕获**：统一处理接口异常，返回标准化的错误响应
- **请求参数日志**：记录所有请求的参数，便于调试和排查问题
- **线程池管理**：支持并发处理请求

## 项目结构

```
pyBaseProject/
├── app/                  # 应用主目录
│   ├── api/              # API 接口目录
│   │   ├── v1/           # v1 版本接口
│   │   │   ├── __init__.py
│   │   │   ├── health_api.py    # 健康检查接口
│   │   │   ├── user_api.py      # 用户接口
│   │   │   ├── demo_api.py      # 示例接口
│   │   │   └── document_api.py  # 文档处理接口
│   │   ├── v2/           # v2 版本接口
│   │   │   ├── __init__.py
│   │   │   ├── health_api.py    # 健康检查接口
│   │   │   ├── user_api.py      # 用户接口
│   │   │   ├── demo_api.py      # 示例接口
│   │   │   └── document_api.py  # 文档处理接口
│   │   └── __init__.py
│   ├── db/               # 数据库相关
│   │   ├── __init__.py
│   │   └── models.py
│   ├── utils/            # 工具类
│   │   ├── concurrency.py  # 并发管理
│   │   └── token_util.py    # Token 工具
│   └── __init__.py
├── cert/                 # SSL 证书目录
│   ├── server.crt
│   └── server.key
├── config/               # 配置文件目录
│   ├── base.py           # 基础配置
│   ├── dev.py            # 开发环境配置
│   ├── test.py           # 测试环境配置
│   └── prod.py           # 生产环境配置
├── logs/                 # 日志目录
├── output/               # 输出目录
├── venv/                 # 虚拟环境
├── main.py               # 主入口文件
├── requirements.txt      # 依赖文件
├── start_service.bat     # 启动脚本
└── start_service_http.bat # HTTP 启动脚本
```

## 安装步骤

### 1. 克隆项目

```bash
git clone <项目地址>
cd pyBaseProject
```

### 2. 创建虚拟环境

```bash
python -m venv venv
```

### 3. 激活虚拟环境

**Windows**：
```bash
venv\Scripts\activate
```

**Linux/Mac**：
```bash
source venv/bin/activate
```

### 4. 安装依赖

```bash
pip install -r requirements.txt
```

## 配置说明

### 环境变量

项目使用 `.env` 文件来管理环境变量，默认使用开发环境配置。

```env
FLASK_ENV=dev  # 环境：dev, test, prod
```

### 配置文件

配置文件位于 `config` 目录下，根据不同环境使用不同的配置文件：

- `dev.py`：开发环境配置
- `test.py`：测试环境配置
- `prod.py`：生产环境配置

主要配置项包括：

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| HOST | 服务主机 | 0.0.0.0 |
| PORT | 服务端口 | 8444 (dev), 8443 (prod) |
| DEBUG | 调试模式 | True (dev), False (prod) |
| LOG_DIR | 日志目录 | logs |
| LOG_FILE | 日志文件 | app_dev.log (dev), app_prod.log (prod) |
| LOG_LEVEL | 日志级别 | DEBUG (dev), INFO (prod) |
| API_KEY | API Key | your-api-key-here |
| API_KEY_HEADER | API Key 头部 | X-API-Key |
| JWT_SECRET_KEY | JWT 密钥 | your-secret-key-here |
| JWT_ACCESS_TOKEN_EXPIRES | Token 过期时间 | 3600 |
| SSL_CERT | SSL 证书路径 | cert/server.crt |
| SSL_KEY | SSL 密钥路径 | cert/server.key |

## 启动服务

### 启动脚本说明

项目提供了两个启动脚本，分别用于启动 HTTPS 服务和 HTTP 服务：

#### 1. `start_service.bat`

**功能**：启动 HTTPS 服务（端口 8443）

**特点**：
- 使用生产环境配置（FLASK_ENV=prod）
- 检查端口 8443 的使用情况并终止占用端口的进程
- 启动服务并显示服务状态
- 服务地址：`https://localhost:8443`
- Swagger 文档：`https://localhost:8443/swagger/`

**使用方法**：
```bash
# Windows
start_service.bat

# Linux/Mac (需要使用 Wine 或其他 Windows 脚本运行工具)
./start_service.bat
```

#### 2. `start_service_http.bat`

**功能**：启动 HTTP 服务（端口 8444）

**特点**：
- 使用开发环境配置（FLASK_ENV=dev）
- 检查端口 8444 的使用情况并终止占用端口的进程
- 启动服务并显示服务状态
- 服务地址：`http://localhost:8444`
- Swagger 文档：`http://localhost:8444/swagger/`

**使用方法**：
```bash
# Windows
start_service_http.bat

# Linux/Mac (需要使用 Wine 或其他 Windows 脚本运行工具)
./start_service_http.bat
```

### 直接运行

如果不想使用启动脚本，也可以直接运行主入口文件：

```bash
python main.py
```

### 启动脚本注意事项

1. **虚拟环境**：启动脚本会检查虚拟环境是否存在，确保你已经创建了虚拟环境并安装了依赖
2. **端口占用**：启动脚本会检查并终止占用端口的进程，可能需要管理员权限
3. **SSL 证书**：HTTPS 服务需要 SSL 证书，确保 `cert` 目录中存在 `server.crt` 和 `server.key` 文件
4. **环境配置**：HTTPS 服务使用生产环境配置，HTTP 服务使用开发环境配置
5. **服务状态**：启动脚本会显示服务的启动状态和访问地址

### 主窗口和日志窗口

#### 主窗口
- **启动方式**：运行启动脚本时，会创建一个新的命令窗口来显示服务的启动状态和访问地址
- **功能**：显示服务的启动过程、运行状态和访问地址
- **关闭方式**：按任意键关闭主窗口，不会影响服务的运行

#### 服务窗口
- **启动方式**：启动脚本会创建一个新的命令窗口（对于 HTTP 服务）或最小化窗口（对于 HTTPS 服务）来运行服务
- **功能**：显示服务的运行日志、请求信息和错误信息
- **关闭方式**：关闭服务窗口会终止服务的运行

#### 日志文件
- **位置**：服务的详细日志会记录在 `logs` 目录中
- **文件命名**：
  - 开发环境：`app_dev.log`
  - 生产环境：`app_prod.log`
- **日志内容**：包含服务的启动信息、请求日志、错误信息和其他重要事件
- **查看方式**：使用文本编辑器打开日志文件查看详细日志

### 日志级别

项目支持不同级别的日志输出，根据环境配置自动调整：

- **开发环境**：DEBUG 级别，显示详细的调试信息
- **生产环境**：INFO 级别，只显示重要的信息和错误

### 日志管理

1. **日志轮转**：日志文件会根据大小自动轮转，避免日志文件过大
2. **日志保留**：默认保留 5 个备份日志文件
3. **日志清理**：定期清理旧的日志文件，释放磁盘空间

## API 文档

服务启动后，可以通过以下地址访问 Swagger 接口文档：

```
http://localhost:8444/swagger/
```

### 接口分组

- **health_v1**：v1 版本健康检查接口
- **health_v2**：v2 版本健康检查接口
- **user_v1**：v1 版本用户接口
- **user_v2**：v2 版本用户接口
- **demo_v1**：v1 版本示例接口
- **demo_v2**：v2 版本示例接口
- **document_v1**：v1 版本文档处理接口
- **document_v2**：v2 版本文档处理接口

## 版本控制说明

项目使用 URL 路径前缀来区分不同版本的接口：

- v1 版本：`/api/v1/`
- v2 版本：`/api/v2/`

例如：
- v1 版本健康检查接口：`/api/v1/health`
- v2 版本健康检查接口：`/api/v2/health`

## 鉴权说明

项目支持两种鉴权方式：

### 1. Token 鉴权

通过 `Authorization` 头部传递 Token：

```
Authorization: Bearer <token>
```

### 2. API Key 鉴权

通过 `X-API-Key` 头部传递 API Key：

```
X-API-Key: <api-key>
```

### 无需鉴权的接口

- 健康检查接口：`/api/v1/health`、`/api/v2/health`
- 登录接口：`/api/user/login`
- Swagger 文档接口：`/swagger/`

## 示例代码

### 登录获取 Token

```python
import requests

url = "http://localhost:8444/api/user/login"
data = {
    "username": "admin",
    "password": "123456"
}

response = requests.post(url, json=data)
print(response.json())
```

### 使用 Token 访问接口

```python
import requests

url = "http://localhost:8444/api/v1/demo/index"
token = "<your-token>"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.json())
```

### 使用 API Key 访问接口

```python
import requests

url = "http://localhost:8444/api/v1/demo/index"
api_key = "<your-api-key>"
headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)
print(response.json())
```

## 常见问题

### 1. Swagger 文档无法访问

- 确保服务已经启动
- 确保 URL 正确：`http://localhost:8444/swagger/`（注意末尾的斜杠）
- 确保防火墙没有阻止端口访问

### 2. 接口鉴权失败

- 检查 Token 是否过期
- 检查 API Key 是否正确
- 检查请求头是否正确设置

### 3. 服务启动失败

- 检查端口是否被占用
- 检查 SSL 证书是否存在
- 检查配置文件是否正确

## 技术栈

- **后端框架**：Flask
- **WSGI 服务器**：Uvicorn
- **接口文档**：Flask-RESTX (Swagger)
- **数据库**：SQLAlchemy (可选)
- **认证**：JWT
- **环境管理**：python-dotenv

## 许可证

MIT