asset_helper/api/README.md

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. 克隆项目并进入目录

cd api

2. 复制环境变量文件

cp .env.example .env
# 根据需要编辑 .env 文件

3. 启动服务

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. 查看日志

make logs
# 或者单独查看
make logs-api
make logs-db
make logs-redis

API 接口

健康检查

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	删除用户

示例请求

# 创建用户
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

常用命令

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