# user-api-tutorial

**Repository Path**: naonao-learn/user-api-tutorial

## Basic Information

- **Project Name**: user-api-tutorial
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# user-api-tutorial

Rust 网络编程教学项目：**HTTP REST 接口（axum）+ gRPC 服务间互调（tonic）+ SQLite 存储**。

专注学：HTTP 方法（GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS）、参数解析、路由、gRPC、proto 代码生成、数据库设计（表/外键/视图）、微服务互调。不做网页前端。

## 架构

```
┌───────────────┐   HTTP (curl)    ┌──────────────────┐   gRPC (tonic)   ┌────────────────┐
│  客户端        │ ───────────────▶ │  rest-gateway    │ ───────────────▶ │  user-service  │
│ (你/测试工具)   │ ◀─────────────── │  (axum :3000)    │ ◀─────────────── │  (tonic:50051) │
└───────────────┘     JSON         └──────────────────┘    protobuf      └───────┬────────┘
   HTTP 服务：对外 REST 接口          纯协议网关，转发请求        数据真正拥有者          │ sqlx
                                                                              ▼
                                                                        ┌────────────┐
                                                                        │ SQLite 文件 │
                                                                        │  data.db    │
                                                                        └────────────┘
```

- **user-service**：gRPC 服务，拥有数据库，所有增删改查在这
- **rest-gateway**：HTTP 服务，收到 REST 请求后转成 gRPC 调 user-service（服务间互调）
- 数据库是本地文件 `data.db`，零安装，含 `users` 与 `orders` 两张表（外键关联）+ 视图 `v_user_orders`

## 快速开始

```powershell
# 终端 1：启动 gRPC 服务（必须先启动）
cargo run -p user-service

# 终端 2：启动 HTTP 服务
cargo run -p rest-gateway

# 测试
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/users
curl http://127.0.0.1:3000/orders   # 订单（联表带出用户名）
curl http://127.0.0.1:3000/external/time  # 外部时间（reqwest 调 timeapi.io，见 TUTORIAL 10.5）
```

## 目录结构

```
user-api-tutorial/
├── Cargo.toml            # workspace 根，管理两个子项目
├── proto/user.proto      # gRPC 协议定义（只写一次，两个服务共享）
├── user-service/         # gRPC 服务端（tonic）+ SQLite（sqlx）
│   ├── build.rs          # proto 代码生成（protoc 由三方包提供，无需安装）
│   └── src/main.rs
├── rest-gateway/         # HTTP 服务（axum），gRPC 客户端
│   ├── build.rs
│   └── src/main.rs
└── TUTORIAL.md           # ★ 全部教学内容（0-11 章，新手从第 0 章开始）
```

## 教学文档

**打开 [TUTORIAL.md](TUTORIAL.md)**，共 0-11 章：

0. 新手起步：配置、运行、启动（workspace / 依赖 / 启动顺序）
1. HTTP 基础：8 种方法、幂等性、状态码
2. REST 设计风格
3. axum 路由与参数提取器
4. 统一错误处理
5. 中间件
6. gRPC 基础与 proto3（HTTP/2、protobuf 编码）
7. proto 的创建、生成与应用（build.rs 剖析、生成产物、加接口实战）
8. 数据库设计：表、类型、外键、视图（users↔orders 关联）
9. tonic 服务端实现
10. 服务间互调（网关调 gRPC、关联资源 URL 设计）
11. 测试命令合集（15 条实测 case 全通过，附 Apifox 图形界面/gRPC 测试指南）