# 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. 配置适当的日志和监控