# webapibycpp

**Repository Path**: walkeringDo/webapibycpp

## Basic Information

- **Project Name**: webapibycpp
- **Description**: 通过cmake构建，基于c++的webapi的开发
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CCPWeb - Web API by C++ (Oat++ Framework)

这是一个基于 C++ 和 Oat++ 框架的安全可靠的 Web API 脚手架框架。该框架提供了完整的 Web API 开发基础结构。

## 功能特性

1. **RESTful API 控制器** - 基于 Oat++ 的 ApiController 实现
2. **数据传输对象 (DTO)** - 使用 Oat++ 的代码生成宏简化开发
3. **服务层** - 业务逻辑封装
4. **SQLite 数据库集成** - 使用 SQLite 实现持久化存储和 ORM 功能
5. **中间件支持** - 日志记录、监控、CORS 等功能
6. **单元测试** - 基于 Oat++ 测试框架
7. **JSON 数据交换** - 支持 JSON 格式的请求和响应数据
8. **API 文档** - 集成 Swagger UI 提供交互式 API 文档
9. **数据验证和错误处理** - 完善的数据验证机制和统一的异常处理
10. **JWT 认证授权** - 基于 JWT 的用户认证和接口授权机制
11. **CORS 支持** - 跨域资源共享支持，包括凭证和 PATCH 方法
12. **配置管理** - 支持从文件和环境变量加载配置

## 目录结构

```
├── CMakeLists.txt              # CMake 构建配置
├── README.md                   # 项目说明文档
├── src/                        # 源代码目录
│   ├── AppComponent.hpp        # 应用组件配置
│   ├── main.cpp                # 主程序入口
│   ├── config/                 # 配置管理
│   ├── controller/             # API 控制器
│   ├── dto/                    # 数据传输对象
│   ├── service/                # 业务服务层
│   ├── repository/             # 数据访问层
│   ├── database/               # 数据库访问层
│   ├── core/                   # 核心组件
│   ├── exception/              # 异常处理
│   ├── middleware/             # 中间件
│   └── swagger/                # Swagger 配置
└── test/                       # 单元测试
```

## 依赖项

- C++17 或更高版本
- [Oat++](https://oatpp.io/) - 现代 Web 框架 (已内置于项目中)
- [Oat++ Swagger](https://github.com/oatpp/oatpp-swagger) - Swagger UI 集成 (已内置于项目中)
- [Spdlog](https://github.com/gabime/spdlog) - 快速的日志库 (已内置于项目中)
- [SQLite](https://www.sqlite.org/index.html) - 轻量级数据库 (已内置于项目中)
- [nlohmann/json](https://github.com/nlohmann/json) - JSON 库 (已内置于项目中)

注意：本项目已将 oatpp、oatpp-swagger、spdlog 和 SQLite 第三方库直接包含在 [third_party](file:///E:/Projects/CPPProjects/webapibycpp/third_party) 目录下，无需通过 vcpkg 或其他包管理器安装。

## 构建项目

使用 CMake 构建项目：

```bash
mkdir build
cd build
cmake ..
cmake --build .
```

构建完成后，可执行文件将在 `build/Debug` 目录下生成（Windows 平台）。

### 在 CLion 中配置

要在 CLion 中正确构建项目：

1. 打开 CLion 并加载项目
2. CLion 会自动识别 CMake 配置并开始构建

## API 接口示例

启动服务后，默认监听在 `localhost:8080`：

### 认证相关接口
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录

### 用户管理接口（需要 JWT Token 认证）
- `POST /api/users` - 创建用户
- `GET /api/users` - 获取所有用户
- `GET /api/users/{id}` - 根据 ID 获取用户
- `PUT /api/users/{id}` - 更新用户信息
- `DELETE /api/users/{id}` - 删除用户
- `GET /api/profile` - 获取当前用户个人信息
- `PUT /api/profile` - 更新当前用户个人信息

### 其他接口
- `GET /health` - 健康检查
- `GET /health/details` - 详细健康检查
- `GET /swagger/ui` - Swagger UI 文档界面
- `GET /api-docs/oas-3.0.0.json` - OpenAPI 3.0 规范 JSON 文件

### POST /api/auth/register 请求示例

```json
{
  "username": "zhangsan",
  "password": "password123",
  "firstName": "张",
  "lastName": "三",
  "email": "zhangsan@example.com"
}
```

### POST /api/auth/login 请求示例

```json
{
  "username": "zhangsan",
  "password": "password123"
}
```

## 中间件

### 日志中间件
记录每个请求的方法和路径。

### 监控中间件
统计请求数量等监控指标。

### CORS 中间件
支持跨域资源共享，包括凭证和 PATCH 方法。

## 数据库集成

项目集成了 SQLite 数据库，提供了完整的 ORM 功能：

- 使用 SQLite 实现数据持久化存储
- 提供了完整的 CRUD 操作
- 支持参数化查询防止 SQL 注入
- 自动创建数据库表结构

数据库文件默认为 `webapp.db`，会在首次运行时自动创建。

## 扩展性

该框架设计具有良好的扩展性：

1. **添加新的 API 接口** - 创建新的 Controller 类
2. **添加新的业务逻辑** - 在 Service 层添加新服务
3. **添加新的数据模型** - 创建新的 DTO 和对应的数据库实体
4. **添加新的中间件** - 实现 RequestInterceptor 接口
5. **添加实体间关联关系** - 可通过数据库外键和自定义服务类实现客户与产品等实体间的关联

## 关于 Oat++ ORM 的说明

本框架使用的是 Oat++ 原生 ORM 实现，需要注意的是 Oat++ 不支持传统意义上的 Code First 开发模式：

1. 需要手动编写 SQL 查询语句
2. 需要手动管理数据库表结构
3. DTO 仅用于数据传输，不自动生成数据库表

这种方式虽然需要更多的手动工作，但提供了更大的灵活性和对数据库操作的精确控制。

## CodeFirst ORM 功能

为了提高开发效率和性能，本框架还集成了 [ORMPP](https://github.com/qicosmos/ormpp) 库，实现了 CodeFirst 功能：

1. 通过 C++ 结构体定义数据模型，自动生成数据库表结构
2. 提供统一的接口支持多种数据库（MySQL、PostgreSQL、SQLite）
3. 编译期反射，自动化实体映射
4. 易于切换数据库类型
5. 支持数据库连接池、事务等高级功能

使用 ORMPP 后，开发者只需专注于业务逻辑，无需手动编写 SQL 语句即可完成大部分数据库操作。

### ORMPP 集成状态

目前，ORMPP 库已完整集成到项目中：

- ORMPP 源码已包含在项目 [third_party/ormpp](file:///E:/Projects/CPPProjects/webapibycpp/third_party/ormpp) 目录下
- UserEntity 结构体已添加正确的 ORM 映射宏定义
- OrmDatabase 类已实现完整的 CRUD 操作接口
- CMakeLists.txt 已配置 ORMPP 库的包含路径

当前实现使用内存存储作为临时解决方案以确保项目可正常编译和运行。要启用完整的数据库功能，只需取消注释相关代码中的 ORMPP 调用即可。

## Swagger API 文档

本框架集成了 Swagger UI，提供交互式的 API 文档：

- 访问 `http://localhost:8080/swagger/ui` 查看 API 文档
- 可以直接在页面上测试 API 接口
- 自动生成 API 接口说明和示例
- 访问 `http://localhost:8080/api-docs/oas-3.0.0.json` 获取 OpenAPI 3.0 规范的 JSON 文件

### 使用说明

在使用 Swagger UI 测试 API 时，请注意以下几点：

1. 邮箱字段需要符合标准邮箱格式（如：user@example.com）
2. 所有必填字段都需要提供有效值
3. 可以在 Swagger UI 页面直接修改请求参数和请求体进行测试

#### JWT Token 认证使用方法

对于需要认证的 API 接口，您需要先进行用户登录获取 Token：

1. 首先调用 `POST /api/auth/login` 接口进行登录
2. 登录成功后，响应中会返回一个 JWT Token
3. 点击右上角的 "Authorize" 按钮
4. 在弹出的对话框中输入 `Bearer {token}` （将 `{token}` 替换为实际的 Token 值）
5. 点击 "Authorize" 确认，之后就可以测试需要认证的接口了

例如：
```
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoidGVzdCIsImV4cCI6MTcyMDA2MzQxOH0.XXXXXXX
```

## 数据验证和错误处理

框架提供了完善的验证和错误处理机制：

1. **数据验证**：服务层对输入数据进行严格验证，包括必填字段检查和格式验证
2. **统一异常处理**：全局异常处理器统一处理各种类型的异常，返回一致的错误格式
3. **详细错误信息**：验证失败时返回具体的字段错误信息，便于前端处理

### 错误响应格式

```json
{
  "success": false,
  "error": "Validation Failed",
  "message": "Validation failed",
  "fieldErrors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "timestamp": "2025-12-02 14:30:45"
}
```

## 框架优化特性

### 1. 配置管理
- 支持从文件和环境变量加载配置
- 灵活的配置项管理

### 2. 异常处理体系
- 统一的全局异常处理器
- 业务异常分类（验证异常、未找到异常等）
- 结构化的错误响应

### 3. 分层架构优化
- Repository 模式实现数据访问层
- Service 层处理业务逻辑
- Controller 层处理 HTTP 请求
- 清晰的职责分离

### 4. 基础类抽象
- BaseController 提供通用响应方法
- BaseService 定义服务层接口
- BaseRepository 定义数据访问接口

### 5. 依赖注入
- 通过构造函数注入依赖
- 松耦合的组件设计

### 6. 健康检查
- 基础健康检查端点
- 详细健康检查信息

### 7. 结构化日志
- 使用 spdlog 记录结构化日志
- 统一的日志格式

### 8. JSON 响应优化
- 统一的 JSON 响应格式
- 支持各种数据类型（DTO、集合、基本类型等）的自动序列化
- 支持分页响应格式

### 9. 现代 C++ 特性应用
- 使用模板特化处理不同类型的数据序列化
- 使用智能指针管理内存
- 使用 STL 容器和算法

## 最近更新

### 代码质量提升
- 修复了 JSON 序列化问题，支持各种 oat++ 数据类型自动转换为 JSON
- 完善了异常处理体系，提供统一的错误响应格式
- 优化了分层架构，明确各层职责
- 修复硬编码路径问题，提高项目可移植性

### 功能增强
- 增加了配置管理模块，支持灵活的配置选项
- 实现了 Repository 模式，提供数据访问层抽象
- 增强了 BaseController，提供丰富的响应方法
- 添加了详细的日志记录和监控中间件
- 集成 Swagger UI，提供交互式 API 文档
- 加强了数据验证机制，提供详细的字段验证错误信息
- 增强 CORS 中间件支持凭证和 PATCH 方法
- 实现 JWT 认证授权机制

### 架构优化
- 使用依赖注入改善组件间的耦合度
- 实现了统一的响应格式，提高 API 一致性
- 优化了类型系统，更好地支持 oat++ DTO 对象

## 许可证

本项目采用 Apache License 2.0 许可证。