快速开始

欢迎使用源丰后端 API！本指南将帮助您快速上手使用我们的 API 服务。

系统要求

• Go 1.19+
• MySQL 8.0+ / PostgreSQL 12+
• Redis 6.0+
• Git

安装步骤

1. 克隆项目

git clone https://github.com/your-org/yuanfeng-backend.git
cd yuanfeng-backend

2. 安装依赖

go mod download

3. 配置环境变量

cp .env.example .env

编辑 .env 文件，配置以下必要参数：

# 数据库配置
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=yuanfeng
DB_USER=root
DB_PASSWORD=your_password

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT 密钥（必须设置）
JWT_SECRET=your-super-secret-jwt-key

# 应用配置
APP_PORT=8080
LOG_LEVEL=info

4. 启动数据库

使用 Docker Compose 启动 MySQL 和 Redis：

docker-compose up -d mysql redis

5. 初始化数据库

# 运行数据库迁移
go run cmd/server/main.go

# 系统会自动创建表结构并初始化基础数据

6. 启动服务

# 开发模式启动
go run cmd/server/main.go

# 或使用开发脚本
./scripts/dev.sh

7. 验证安装

访问以下地址验证服务是否正常运行：

• API 服务: http://localhost:8080
• 健康检查: http://localhost:8080/health
• Swagger 文档: http://localhost:8080/swagger/index.html

API 基础信息

基础 URL

http://localhost:8080/api/v1

认证方式

本 API 使用 JWT (JSON Web Token) 进行身份认证。

1. 首先调用登录接口获取 token
2. 在后续请求中携带 token：Authorization: Bearer <your-token>

响应格式

所有 API 响应都遵循统一的格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据内容
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

错误响应格式：

{
  "code": 400,
  "message": "请求参数错误",
  "error": "详细错误信息",
  "timestamp": "2024-01-01T12:00:00Z"
}

快速测试

1. 用户注册

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123",
    "phone": "13800138000"
  }'

2. 用户登录

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123"
  }'

3. 获取用户信息

# 替换 <your-token> 为登录获取的 token
curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer <your-token>"

开发工具推荐

API 测试工具

• Postman: 功能强大的 API 测试工具
• Insomnia: 简洁的 REST 客户端
• curl: 命令行工具

代码生成

• swagger-codegen: 根据 Swagger 文档生成客户端代码
• openapi-generator: 支持多种语言的代码生成

常见问题

Q: 忘记管理员密码怎么办？

A: 可以通过数据库直接修改，或重新初始化数据。

Q: 如何修改端口？

A: 在 .env 文件中修改 APP_PORT 配置。

Q: 如何开启 HTTPS？

A: 使用反向代理（如 Nginx）配置 SSL 证书。

Q: 数据库迁移失败怎么办？

A: 检查数据库连接配置，确保有足够的权限创建表。

下一步

• 阅读认证授权指南
• 查看完整的 API 文档
• 尝试示例代码
• 了解错误处理

如有问题，请查看 常见问题 或提交 Issue。