164 lines
3.5 KiB
Markdown
164 lines
3.5 KiB
Markdown
# RESTful API 工程
|
|
|
|
基于 Golang + Redis + Postgres 的单机多服务 RESTful API 工程。
|
|
|
|
## 技术栈
|
|
|
|
- **Golang**: 1.25.8-alpine3.23 - API 服务
|
|
- **Postgres**: 18.3-alpine3.23 - 关系型数据库
|
|
- **Redis**: 8.6.2-alpine - 缓存服务
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
.
|
|
├── api/ # API 服务代码
|
|
│ ├── config/ # 配置管理
|
|
│ ├── handlers/ # HTTP 处理器
|
|
│ ├── models/ # 数据模型
|
|
│ ├── router/ # 路由配置
|
|
│ ├── Dockerfile # API 服务镜像
|
|
│ ├── go.mod # Go 模块定义
|
|
│ └── main.go # 入口文件
|
|
├── migrations/ # 数据库迁移脚本
|
|
├── docker-compose.yml # Docker Compose 配置
|
|
├── Makefile # 常用命令
|
|
├── .env # 环境变量（本地开发）
|
|
└── .env.example # 环境变量示例
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
### 1. 克隆项目并进入目录
|
|
|
|
```bash
|
|
cd api
|
|
```
|
|
|
|
### 2. 复制环境变量文件
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# 根据需要编辑 .env 文件
|
|
```
|
|
|
|
### 3. 启动服务
|
|
|
|
```bash
|
|
make up
|
|
# 或者
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 4. 验证服务
|
|
|
|
- API: http://localhost:8080
|
|
- Health Check: http://localhost:8080/health
|
|
- API Docs: http://localhost:8080/api/v1/ping
|
|
|
|
### 5. 查看日志
|
|
|
|
```bash
|
|
make logs
|
|
# 或者单独查看
|
|
make logs-api
|
|
make logs-db
|
|
make logs-redis
|
|
```
|
|
|
|
## API 接口
|
|
|
|
### 健康检查
|
|
|
|
```bash
|
|
curl http://localhost:8080/health
|
|
```
|
|
|
|
### 用户接口
|
|
|
|
| 方法 | 路径 | 描述 |
|
|
|------|------|------|
|
|
| GET | /api/v1/ping | 测试接口 |
|
|
| GET | /api/v1/users | 获取用户列表 |
|
|
| POST | /api/v1/users | 创建用户 |
|
|
| GET | /api/v1/users/:id | 获取单个用户 |
|
|
| PUT | /api/v1/users/:id | 更新用户 |
|
|
| DELETE | /api/v1/users/:id | 删除用户 |
|
|
|
|
### 示例请求
|
|
|
|
```bash
|
|
# 创建用户
|
|
curl -X POST http://localhost:8080/api/v1/users \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name":"王五","email":"wangwu@example.com"}'
|
|
|
|
# 获取用户列表
|
|
curl http://localhost:8080/api/v1/users
|
|
|
|
# 获取单个用户
|
|
curl http://localhost:8080/api/v1/users/1
|
|
```
|
|
|
|
## 常用命令
|
|
|
|
```bash
|
|
# 构建镜像
|
|
make build
|
|
|
|
# 启动服务
|
|
make up
|
|
|
|
# 停止服务
|
|
make down
|
|
|
|
# 重启服务
|
|
make restart
|
|
|
|
# 查看日志
|
|
make logs
|
|
|
|
# 进入容器
|
|
make shell-api # 进入 API 容器
|
|
make shell-db # 进入数据库
|
|
make shell-redis # 进入 Redis
|
|
|
|
# 本地开发
|
|
make tidy # 整理依赖
|
|
make test # 运行测试
|
|
make run # 本地运行
|
|
|
|
# 清理环境
|
|
make clean # 清理所有容器和数据
|
|
```
|
|
|
|
## 环境变量
|
|
|
|
| 变量名 | 默认值 | 描述 |
|
|
|--------|--------|------|
|
|
| APP_ENV | development | 应用环境 |
|
|
| APP_PORT | 8080 | API 端口 |
|
|
| DB_HOST | localhost | 数据库主机 |
|
|
| DB_PORT | 5432 | 数据库端口 |
|
|
| DB_USER | postgres | 数据库用户 |
|
|
| DB_PASSWORD | postgres | 数据库密码 |
|
|
| DB_NAME | appdb | 数据库名 |
|
|
| REDIS_HOST | localhost | Redis 主机 |
|
|
| REDIS_PORT | 6379 | Redis 端口 |
|
|
| REDIS_PASSWORD | | Redis 密码 |
|
|
|
|
## 开发说明
|
|
|
|
1. **添加新接口**: 在 `api/handlers/` 下添加处理器，在 `api/router/router.go` 中注册路由
|
|
2. **添加模型**: 在 `api/models/` 下添加数据模型
|
|
3. **数据库迁移**: 在 `migrations/` 下添加 SQL 文件
|
|
|
|
## 部署
|
|
|
|
生产环境部署前请确保：
|
|
|
|
1. 修改 `.env` 中的敏感信息（密码等）
|
|
2. 设置 `APP_ENV=production`
|
|
3. 使用 HTTPS
|
|
4. 配置适当的日志和监控
|