# prime_number_server

**Repository Path**: panarea/prime_number_server

## Basic Information

- **Project Name**: prime_number_server
- **Description**: Rust 语言编写的质数服务器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 质因数分解服务器

这是一个高性能的质因数分解网络服务器，使用 Rust 语言实现。

## 功能特性

1. **基本功能**：提供 API 接口，接收大整数并返回质因数分解结果
2. **高效缓存**：使用 BTreeMap 实现高效缓存系统，快速响应已分解的数
3. **多线程并行**：
   - 查询(search)线程：响应客户端请求
   - 挖矿(find)线程：提前计算并缓存耗时较长的分解结果
4. **动态负载调整**：根据并发请求数动态调整查询和挖矿线程的分配

## 构建和运行

### 构建项目

```bash
cargo build --release
```

### 运行服务器

```bash
cargo run --release
```

服务器默认监听 `0.0.0.0:3000` 端口。

## 🌐 Web 界面

启动服务器后，在浏览器中访问 **http://localhost:3000** 即可使用友好的 Web 界面：

- ✨ 美观的现代化界面
- 🔢 输入框直接输入数字进行分解
- 📊 实时显示分解结果
- 🎯 示例链接快速测试
- 📈 查看服务器统计信息

### 使用方式

1. 启动服务器：`cargo run`
2. 打开浏览器访问：http://localhost:3000
3. 在输入框中输入数字，点击"分解"按钮
4. 查看结果，包括是否为质数、质因数列表等

## API 接口

### 1. 质因数分解 (POST)

**请求：**
```bash
curl -X POST http://localhost:3000/factorize \
  -H "Content-Type: application/json" \
  -d '{"number": "123456789"}'
```

**响应：**
```json
{
  "number": "123456789",
  "result": "3^2 × 3607 × 3803",
  "is_prime": false,
  "factors": [["3", 2], ["3607", 1], ["3803", 1]],
  "cached": false
}
```

### 2. 质因数分解 (GET)

**请求：**
```bash
# 浏览器访问（返回HTML页面）
http://localhost:3000/factorize/123456789

# API调用（返回JSON）
curl http://localhost:3000/factorize/123456789
```

**响应：** 
- 浏览器访问：返回友好的HTML页面
- API调用：返回JSON格式数据

### 3. 获取统计信息

**请求：**
```bash
# 浏览器访问（返回HTML页面）
http://localhost:3000/stats

# API调用（返回JSON）
curl http://localhost:3000/api/stats
```

**响应：**
```json
{
  "cache": {
    "size": 150,
    "max_size": 10000
  },
  "load": {
    "active_requests": 5,
    "query_workers": 6,
    "mining_workers": 2,
    "total_workers": 8
  }
}
```

### 4. 健康检查

**请求：**
```bash
curl http://localhost:3000/health
```

**响应：**
```json
{
  "status": "ok"
}
```

## 架构设计

### 模块说明

- **factorization.rs**: 质因数分解算法实现
- **cache.rs**: 高效缓存系统（使用 BTreeMap）
- **worker.rs**: 查询和挖矿工作线程池
- **load_balancer.rs**: 动态负载调整机制
- **server.rs**: HTTP 服务器和 API 端点
- **main.rs**: 程序入口，整合所有模块

### 缓存策略

- 只缓存计算时间超过阈值的分解结果（查询：10ms，挖矿：50ms）
- 使用 BTreeMap 提供有序、高效的查询
- 缓存大小可配置（默认 10000 条）

### 负载调整策略

- **高负载**（活跃请求 > 总线程数 × 50%）：增加查询线程（最多 80%），减少挖矿线程（最少 20%）
- **低负载**（活跃请求 < 总线程数 × 20%）：减少查询线程（最少 40%），增加挖矿线程（最多 60%）
- 每 5 秒检查并调整一次

## 配置参数

在 `src/main.rs` 中可以修改以下配置：

- `total_workers`: 总工作线程数（默认：CPU 核心数）
- `cache_size`: 缓存最大条目数（默认：10000）
- `server_port`: 服务器端口（默认：3000）

## 测试示例

### 使用 Web 界面（推荐）

1. 启动服务器：`cargo run`
2. 打开浏览器访问：http://localhost:3000
3. 在界面中输入数字并点击"分解"按钮

### 使用 API

```bash
# 测试小数字
curl http://localhost:3000/factorize/12

# 测试质数
curl http://localhost:3000/factorize/17

# 测试大数字
curl -X POST http://localhost:3000/factorize \
  -H "Content-Type: application/json" \
  -d '{"number": "9876543210"}'

# 查看统计信息（JSON）
curl http://localhost:3000/api/stats
```

## 评分要求对应

✅ **基本功能** (+50分)：提供合数验证和质因数分解服务  
✅ **高效缓存** (+20分)：使用 BTreeMap 实现高效缓存，提供快速查询  
✅ **多线程并行** (+20分)：查询和挖矿任务采用多线程并行，线程数可配置  
✅ **动态负载调整** (+10分)：根据并发情况动态调整线程分配  

## 依赖库

- `axum`: 现代异步 Web 框架
- `tokio`: 异步运行时
- `num-bigint`: 大整数支持
- `parking_lot`: 高性能读写锁
- `arc-swap`: 无锁原子引用交换
- `serde`: 序列化/反序列化

## 许可证

本项目为课程作业项目。

---

# 快速启动指南

## 前置要求

1. **安装 Rust**（如果尚未安装）
   - 访问 https://www.rust-lang.org/tools/install
   - 或使用命令：`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
   - Windows 用户可以直接下载安装程序

2. **验证安装**
   ```bash
   rustc --version
   cargo --version
   ```

## 启动步骤

### 方法一：直接运行（开发模式）

```bash
cargo run
```

这会自动编译并运行项目。首次运行会下载依赖，可能需要几分钟。

### 方法二：先编译再运行（推荐用于生产）

```bash
# 编译（优化版本）
cargo build --release

# 运行编译后的程序
./target/release/prime-factorization-server
# Windows 用户使用：
# .\target\release\prime-factorization-server.exe
```

## 运行后

服务器启动后会显示：

```
🚀 启动质因数分解服务器...
📊 配置信息:
  - 总工作线程数: 8
  - 缓存大小: 10000
  - 服务器端口: 3000
🔧 初始线程分配:
  - 查询线程: 5
  - 挖矿线程: 3
✅ 服务器已启动，监听端口 3000
📝 API文档:
  - POST http://localhost:3000/factorize
  - GET  http://localhost:3000/factorize/:number
  - GET  http://localhost:3000/stats
  - GET  http://localhost:3000/health
```

## 测试 API

### 使用浏览器

直接在浏览器中访问：
- http://localhost:3000/factorize/12
- http://localhost:3000/stats
- http://localhost:3000/health

### 使用 curl（命令行）

```bash
# 测试质因数分解
curl http://localhost:3000/factorize/12

# 测试质数
curl http://localhost:3000/factorize/17

# 使用 POST 方法
curl -X POST http://localhost:3000/factorize \
  -H "Content-Type: application/json" \
  -d "{\"number\": \"123456789\"}"

# 查看统计信息
curl http://localhost:3000/stats
```

### 使用 PowerShell（Windows）

```powershell
# 测试质因数分解
Invoke-RestMethod -Uri "http://localhost:3000/factorize/12"

# 使用 POST 方法
$body = @{ number = "123456789" } | ConvertTo-Json
Invoke-RestMethod -Uri "http://localhost:3000/factorize" -Method Post -Body $body -ContentType "application/json"

# 查看统计信息
Invoke-RestMethod -Uri "http://localhost:3000/stats"
```

### 使用测试脚本

```bash
# Linux/Mac
bash examples/test_api.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File examples/test_api.ps1
```

## 常见问题

### 1. 端口被占用

如果 3000 端口被占用，可以修改 `src/main.rs` 中的 `server_port` 变量：

```rust
let server_port = 3000; // 改为其他端口，如 8080
```

### 2. 编译错误

如果遇到编译错误，尝试：

```bash
# 更新依赖
cargo update

# 清理并重新编译
cargo clean
cargo build
```

### 3. 性能优化

对于生产环境，建议使用 release 模式：

```bash
cargo build --release
./target/release/prime-factorization-server
```

## 停止服务器

在运行服务器的终端中按 `Ctrl+C` 即可停止服务器。

---

# 服务器启动和测试说明

## 🚀 启动服务器

### 方式一：开发模式（自动编译并运行）
```powershell
cargo run
```

### 方式二：发布模式（先编译，再运行）
```powershell
# 1. 编译
cargo build --release

# 2. 运行
.\target\release\prime-factorization-server.exe
```

## 📝 启动后你会看到

服务器启动成功后会显示：
```
🚀 启动质因数分解服务器...
📊 配置信息:
  - 总工作线程数: X
  - 缓存大小: 10000
  - 服务器端口: 3000
🔧 初始线程分配:
  - 查询线程: X
  - 挖矿线程: X
✅ 服务器已启动，监听端口 3000
```

## 🧪 测试 API

### 1. 使用浏览器（最简单）

打开浏览器，访问以下地址：
- **健康检查**: http://localhost:3000/health
- **质因数分解**: http://localhost:3000/factorize/12
- **统计信息**: http://localhost:3000/stats

### 2. 使用 PowerShell

在新的 PowerShell 窗口中运行：

```powershell
# 健康检查
Invoke-RestMethod -Uri "http://localhost:3000/health"

# 测试小数字
Invoke-RestMethod -Uri "http://localhost:3000/factorize/12"

# 测试质数
Invoke-RestMethod -Uri "http://localhost:3000/factorize/17"

# 测试大数字（POST）
$body = @{ number = "123456789" } | ConvertTo-Json
Invoke-RestMethod -Uri "http://localhost:3000/factorize" -Method Post -Body $body -ContentType "application/json"

# 查看统计信息
Invoke-RestMethod -Uri "http://localhost:3000/stats"
```

### 3. 使用测试脚本

```powershell
powershell -ExecutionPolicy Bypass -File examples\test_api.ps1
```

### 4. 使用 curl（如果有）

```bash
curl http://localhost:3000/factorize/12
curl http://localhost:3000/stats
```

## 📊 预期响应示例

### 质因数分解响应
```json
{
  "number": "12",
  "result": "2^2 × 3",
  "is_prime": false,
  "factors": [
    ["2", 2],
    ["3", 1]
  ],
  "cached": false
}
```

### 质数响应
```json
{
  "number": "17",
  "result": "质数",
  "is_prime": true,
  "factors": [],
  "cached": false
}
```

### 统计信息响应
```json
{
  "cache": {
    "size": 5,
    "max_size": 10000,
    "hits": 10,
    "misses": 5,
    "hit_rate": 66.67
  },
  "load": {
    "active_requests": 0,
    "query_workers": 5,
    "mining_workers": 3,
    "total_workers": 8
  }
}
```

## ⚠️ 常见问题

### 端口被占用
如果 3000 端口被占用，修改 `src/main.rs` 中的端口号：
```rust
let server_port = 8080; // 改为其他端口
```

### 编译时间较长
首次编译需要下载依赖，可能需要 5-10 分钟，请耐心等待。

### 停止服务器
在运行服务器的终端中按 `Ctrl+C`

## 🎯 快速测试流程

1. **打开第一个终端**，运行服务器：
   ```powershell
   cargo run
   ```

2. **等待服务器启动**（看到 "✅ 服务器已启动" 消息）

3. **打开第二个终端**（或浏览器），测试 API：
   ```powershell
   # 快速测试
   Invoke-RestMethod -Uri "http://localhost:3000/factorize/12"
   ```

4. **查看结果**，应该看到 JSON 格式的响应

---

# 编译错误修复说明

## ✅ 已修复的问题

### 1. `src/factorization.rs:142` - 运算符错误
**错误**: `cannot calculate the remainder of &&BigUint divided by BigUint`

**修复**: 将 `&n` 改为 `n`，因为 `n` 已经是 `&BigUint` 类型
```rust
// 修复前
if &n % BigUint::from(2u32) == BigUint::zero() {

// 修复后
if n % BigUint::from(2u32) == BigUint::zero() {
```

### 2. `src/load_balancer.rs:59` 和 `64` - 类型不匹配
**错误**: `expected usize, found Arc<usize>`

**修复**: 需要双重解引用 `Arc<usize>` 才能得到 `usize`
```rust
// 修复前
pub fn get_query_workers(&self) -> usize {
    *self.query_workers.load()
}

// 修复后
pub fn get_query_workers(&self) -> usize {
    **self.query_workers.load()
}
```

### 3. `src/worker.rs:107` - 布尔运算符错误
**错误**: `cannot apply unary operator ! to type Arc<bool>`

**修复**: 需要双重解引用 `Arc<bool>` 才能使用 `!` 运算符
```rust
// 修复前
if !*should_continue_clone.load() {

// 修复后
if !**should_continue_clone.load() {
```

### 4. 清理未使用的导入
- 移除了 `src/server.rs` 中未使用的 `FactorizationResult` 导入
- 移除了 `src/main.rs` 中未使用的 `Router` 导入
- 修复了未使用变量的警告

## ✅ 编译状态

现在项目可以成功编译！运行以下命令启动服务器：

```powershell
cargo run
```

或者先编译再运行：

```powershell
cargo build --release
.\target\release\prime-factorization-server.exe
```

## ⚠️ 剩余的警告

这些警告不影响程序运行，只是提示某些代码未使用：
- `cached_at` 字段未使用（保留用于未来扩展）
- `clear` 方法未使用（保留用于未来扩展）
- `prime` 函数未使用（保留用于未来扩展）
- `is_prime` 函数未使用（保留用于未来扩展）
- 一些工作池的字段和方法未使用（这些是正常的，因为它们在运行时使用）

## 🚀 下一步

1. 运行服务器：`cargo run`
2. 测试 API：访问 http://localhost:3000/factorize/12
3. 查看统计：访问 http://localhost:3000/stats

服务器现在应该可以正常启动了！

---

# 更新日志

## 2024 - Web 界面优化

### ✨ 新增功能

1. **友好的 Web 界面**
   - 美观的现代化 UI 设计
   - 渐变背景和卡片式布局
   - 响应式设计，支持移动端

2. **交互式功能**
   - 输入框直接输入数字进行分解
   - 实时显示计算结果
   - 示例链接快速测试
   - 支持回车键提交

3. **智能响应**
   - 浏览器访问返回 HTML 页面
   - API 调用返回 JSON 数据
   - 自动检测 Accept 头

4. **统计信息页面**
   - 美观的统计信息展示页面
   - 显示缓存和负载信息
   - 提供返回首页链接

### 🎨 界面特性

- **首页** (http://localhost:3000/)
  - 输入框和分解按钮
  - 实时结果显示
  - 示例数字快速测试
  - 统计信息链接

- **统计页面** (http://localhost:3000/stats)
  - 缓存统计信息
  - 负载统计信息
  - 返回首页链接

### 📝 API 变更

- `GET /` - 现在返回 HTML 页面（之前返回纯文本）
- `GET /factorize/:number` - 根据 Accept 头返回 HTML 或 JSON
- `GET /stats` - 返回 HTML 页面
- `GET /api/stats` - 新增，返回 JSON 格式的统计信息

### 🔧 技术改进

- 添加了 `tower-http` 的 `fs` 功能支持
- HTML 内容通过 `include_str!` 宏嵌入到二进制文件中
- 支持静态文件服务（`/static` 路径）

### 📦 文件结构

```
static/
  └── index.html    # Web 界面 HTML 文件
```

### 🚀 使用方式

1. 启动服务器：`cargo run`
2. 打开浏览器访问：http://localhost:3000
3. 在输入框中输入数字，点击"分解"按钮
4. 查看结果，包括是否为质数、质因数列表等

### 💡 用户体验改进

- ✅ 不再需要手动修改 URL
- ✅ 清晰的输入提示和操作说明
- ✅ 美观的结果展示
- ✅ 示例链接帮助用户快速上手
- ✅ 实时反馈和错误提示

---

# Web 界面优化说明

## 🎯 优化目标

解决原服务器易用性差的问题：
- ❌ 访问根路径只有纯文本，没有使用说明
- ❌ 用户不知道如何操作
- ❌ 需要手动修改 URL 才能测试
- ❌ 没有友好的界面和提示

## ✅ 优化内容

### 1. 友好的首页界面

访问 **http://localhost:3000/** 现在会显示：

- 🎨 **美观的现代化界面**
  - 渐变背景（紫色主题）
  - 卡片式布局
  - 响应式设计

- 📝 **清晰的输入区域**
  - 大号输入框，带有占位符提示
  - 醒目的"分解"按钮
  - 支持回车键快速提交

- 💡 **示例链接**
  - 提供 5 个示例数字（12, 17, 100, 123456789, 9876543210）
  - 点击即可快速测试
  - 帮助用户理解功能

- 🔗 **导航链接**
  - 统计信息页面链接
  - 方便查看服务器状态

### 2. 智能结果展示

分解结果会以友好的方式显示：

- **质数标识**：绿色徽章显示"质数"
- **合数标识**：蓝色徽章显示"合数"
- **缓存标识**：橙色徽章显示"缓存"（如果结果来自缓存）
- **质因数列表**：以卡片形式展示所有质因数
- **数学表达式**：显示完整的分解表达式（如：2² × 3）

### 3. 统计信息页面

访问 **http://localhost:3000/stats** 显示：

- 📊 **缓存统计**
  - 当前缓存条目数
  - 最大缓存大小
  - 缓存命中次数
  - 缓存未命中次数
  - 缓存命中率

- ⚡ **负载统计**
  - 活跃请求数
  - 查询线程数
  - 挖矿线程数
  - 总线程数

### 4. 智能响应类型

服务器会根据请求类型返回不同格式：

- **浏览器访问** → 返回 HTML 页面
- **API 调用** → 返回 JSON 数据

例如：
- 浏览器访问 `http://localhost:3000/factorize/12` → 显示 HTML 页面
- `curl http://localhost:3000/factorize/12` → 返回 JSON

### 5. 用户体验改进

- ✅ **自动填充**：如果 URL 中包含数字，页面会自动填充并执行分解
- ✅ **加载提示**：计算时显示"计算中，请稍候..."
- ✅ **错误提示**：输入错误时显示友好的错误信息
- ✅ **禁用按钮**：计算过程中按钮自动禁用，防止重复提交

## 📁 文件结构

```
static/
  └── index.html    # Web 界面 HTML 文件（包含 CSS 和 JavaScript）
```

## 🚀 使用方式

### 启动服务器

```bash
cargo run
```

### 访问界面

1. **打开浏览器**访问：http://localhost:3000
2. **输入数字**：在输入框中输入要分解的数字
3. **点击分解**：点击"分解"按钮或按回车键
4. **查看结果**：结果会显示在下方

### 快速测试

- 点击示例链接（12, 17, 100 等）
- 或直接在浏览器地址栏输入：http://localhost:3000/factorize/123456789

## 🎨 界面预览

### 首页特点

- 渐变紫色背景
- 白色卡片容器
- 大号输入框
- 示例链接区域
- 统计信息链接

### 结果展示

- 清晰的标题和徽章
- 数学表达式展示
- 质因数卡片列表
- 缓存状态提示

## 🔧 技术实现

1. **HTML 嵌入**：使用 `include_str!` 宏将 HTML 嵌入到二进制文件中
2. **静态文件服务**：支持 `/static` 路径的静态文件服务
3. **Accept 头检测**：根据请求的 Accept 头返回 HTML 或 JSON
4. **JavaScript 交互**：使用原生 JavaScript 实现前端交互

## 📝 API 端点

| 端点 | 说明 | 返回类型 |
|------|------|----------|
| `GET /` | 首页 | HTML |
| `GET /factorize/:number` | 质因数分解 | HTML/JSON（根据 Accept 头） |
| `GET /stats` | 统计信息页面 | HTML |
| `GET /api/stats` | 统计信息 API | JSON |
| `POST /factorize` | 质因数分解 API | JSON |
| `GET /health` | 健康检查 | JSON |

## ✨ 改进效果

### 之前
- ❌ 用户不知道如何使用
- ❌ 需要手动修改 URL
- ❌ 没有使用说明
- ❌ 纯文本响应

### 现在
- ✅ 清晰的界面和操作说明
- ✅ 输入框直接输入
- ✅ 示例链接快速测试
- ✅ 美观的结果展示
- ✅ 友好的错误提示

## 🎉 总结

通过添加友好的 Web 界面，服务器的易用性得到了显著提升：

1. **零学习成本**：用户打开页面就知道如何使用
2. **操作简单**：输入数字，点击按钮即可
3. **结果清晰**：美观的展示方式，一目了然
4. **功能完整**：保留了所有 API 功能，同时提供了 Web 界面

现在用户可以：
- 直接在浏览器中使用，无需了解 API
- 通过示例快速了解功能
- 查看服务器统计信息
- 享受流畅的用户体验