# AppBase

**Repository Path**: xuxml/app-base

## Basic Information

- **Project Name**: AppBase
- **Description**: 基于 .NET 10 构建的高性能、模块化 Web API 基础框架。本项目旨在提供一个开箱即用的后端开发脚手架，专为移动端 APP 和 H5 应用设计，集成了现代 Web 开发所需的常用功能和最佳实践。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AppBase API Framework

基于 .NET 10 构建的高性能、模块化 Web API 基础框架。本项目旨在提供一个开箱即用的后端开发脚手架，专为移动端 APP 和 H5 应用设计，集成了现代 Web 开发所需的常用功能和最佳实践。

## ✨ 核心特性

*   **最新技术栈**: 基于 **.NET 10** 开发，享受最新的性能优化和语言特性。
*   **分层架构**: 清晰的项目结构（WebApi, Service, Core, Common, Utils），易于维护和扩展。
*   **ORM**: 集成 **SqlSugar**，支持多种数据库（默认配置为 Oracle），提供强大的数据库操作能力。
*   **安全认证**:
    *   **JWT**: 内置 JWT 身份认证机制。
    *   **API 签名验证**: 自定义中间件实现请求签名校验，防止重放攻击和数据篡改。
*   **统一响应格式**: 封装 `ResultDto`，统一 API 返回结构，简化前端处理。
*   **短信服务**: 内置短信验证码发送与校验逻辑，支持频率限制。
*   **高性能缓存**: 集成 **Redis** 缓存支持。
*   **日志系统**: 使用 **NLog** 进行结构化日志记录。
*   **API 文档**: 集成 **Scalar** / OpenAPI，提供友好的接口文档体验。
*   **工具集**: 包含常用的加密、辅助工具类。

## 📦 集成第三方库

本项目精选了以下成熟的第三方库，以提高开发效率和系统稳定性：

*   **SqlSugarCore**: 轻量级、高性能的 ORM 框架，支持多种数据库，提供便捷的 Lambda 表达式查询。
*   **StackExchange.Redis**: 高性能的 Redis 客户端，用于实现分布式缓存和数据存储。
*   **NLog.Web.AspNetCore**: 灵活且强大的日志记录库，支持多种日志目标（文件、数据库、控制台等）。
*   **Mapster**: 高性能的对象映射库，用于 DTO 与实体之间的快速转换。
*   **Scalar.AspNetCore**: 现代化的 API 文档 UI，替代传统的 Swagger UI，提供更好的交互体验。
*   **Microsoft.AspNetCore.OpenApi**: 生成符合 OpenAPI 规范的 API 文档。

## 📂 项目结构

| 项目名称 | 说明 |
| :--- | :--- |
| **AppBase.WebApi** | Web API 入口，包含控制器、中间件、启动配置。 |
| **AppBase.Service** | 业务逻辑层，处理具体的业务规则。 |
| **AppBase.Core** | 核心层，包含领域实体、核心业务对象。 |
| **AppBase.Common** | 公共层，包含 DTOs、枚举、常量、通用扩展方法。 |
| **AppBase.Utils** | 工具层，包含加密、字符串处理等底层工具类。 |

## 🚀 快速开始

### 前置要求

*   [.NET 10 SDK](https://dotnet.microsoft.com/download)
*   Oracle Database (或其他 SqlSugar 支持的数据库)
*   Redis Server

### 配置说明

在 `AppBase.WebApi` 项目的 `appsettings.json` 中配置以下关键项：

```json
{
  "ConnectionStrings": {
    "AppBase": "Data Source=...;User Id=...;Password=..."
  },
  "Redis": {
    "ConnectionString": "localhost:6379"
  },
  "Jwt": {
    "SigningKey": "your-secure-signing-key-at-least-32-chars",
    "ExpiresMinutes": 120,
    "RefreshTokenExpiresDays": 30
  },
  "Signature": {
    "Secret": "your-api-signature-secret"
  }
}
```

### 运行项目

1.  克隆仓库到本地。
2.  配置数据库连接字符串和 Redis 连接。
3.  在根目录下运行：

```bash
dotnet restore
dotnet run --project AppBase.WebApi
```

4.  访问 `https://localhost:5001/Scalar` (或配置的端口) 查看 API 文档。

## 🛡️ 中间件机制

项目内置了多个自定义中间件来增强安全性与功能：

1.  **RequestHeaderMiddleware**: 解析标准请求头（如 Unix 时间戳、设备 ID、渠道 ID）。
2.  **JwtAuthenticationMiddleware**: 处理用户身份认证。
3.  **SignatureVerificationMiddleware**: 验证 API 请求签名的合法性。
    *   支持通过 `[NoSignature]` 特性跳过特定接口的验签。

## 🔐 API 签名规则

为了保证接口调用的安全性，防止参数被篡改和请求重放，所有非豁免的 API 请求（`/api/*`）都需要包含签名。

### 1. 必要的请求头

客户端发起请求时，需要在 HTTP Header 中包含以下字段（由 `RequestHeaderMiddleware` 解析）：

| 字段名 | 说明 | 示例 |
| :--- | :--- | :--- |
| `X-Signature` | 最终生成的签名字符串 | `a1b2c3d4...` |
| `Unix` | 当前 Unix 时间戳 | `1715678900` |
| `ChannelId` | 渠道标识 | `AppStore` |
| `DeviceId` | 设备唯一标识 | `uuid-1234-5678` |

### 2. 签名生成算法

签名计算公式如下：

```plaintext
RawString = Secret + Unix + ChannelId + DeviceId + HttpBody
Signature = MD5(RawString.ToLower())
```

**步骤说明：**

1.  **拼接字符串**: 按照顺序拼接 `Secret`（密钥）、`Unix`、`ChannelId`、`DeviceId` 和 `HttpBody`（请求体原始内容）。
2.  **转小写**: 将拼接后的字符串全部转换为小写。
3.  **MD5 加密**: 对转换后的字符串进行 MD5 加密，生成 32 位十六进制字符串。

**注意：**
*   `Secret` 需在服务端 `appsettings.json` 中配置 (`Signature:Secret`)，并下发给客户端安全存储。
*   `HttpBody` 为请求体的原始 JSON 字符串。如果是 GET 请求，Body 为空字符串。

### 3. 豁免签名

对于登录、注册或公开的接口，可以在 Controller 或 Action 上添加 `[NoSignature]` 特性来跳过签名验证。

```csharp
[HttpPost("login")]
[NoSignature]
public async Task<ResultDto> Login(...) { ... }
```

## 📝 开发规范

*   **控制器**: 继承自 `AppBaseControllerBase`。
*   **服务**: 继承自 `ApplicationService`，通过依赖注入使用。
*   **数据库操作**: 使用 `ISqlSugarClient` 进行数据访问。