JY API 项目开发规范

📋 概述

本文档定义了JY API项目的开发规范和标准，确保代码质量、文档完整性和团队协作效率。

🔥 核心规则

规则 #1：接口文档强制要求 📖

每个新建的API接口都必须提供对应的使用说明文档（Markdown格式）

1.1 文档命名规范

API_{接口功能}_{版本}.md

示例:

• API_CREATE_DRAFT.md - 创建草稿接口文档
• API_EASY_CREATE_MATERIAL.md - 创建素材接口文档
• API_USER_MANAGEMENT_V2.md - 用户管理接口文档（第2版）

1.2 文档存放位置

项目根目录/
├── API_接口名.md          # 单接口文档
├── API_USAGE_GUIDE.md     # 综合使用指南
└── docs/                  # 其他文档目录
    ├── api/               # API详细文档
    └── guides/            # 使用指南

1.3 文档内容要求

每个接口文档必须包含以下标准章节：

# {接口名称} API 文档

## 接口信息
- 接口地址: POST/GET/PUT/DELETE /api/xxx
- 接口功能: 简述接口用途

## 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|

## 响应格式
### 成功响应
### 错误响应

## 使用示例
### cURL 示例
### JavaScript 示例
### 其他语言示例（可选）

## 注意事项
## 错误排查
## 更新日志

1.4 代码审查检查项

在代码审查时，必须验证：

• ✅ 接口文档是否存在
• ✅ 文档内容是否完整
• ✅ 示例代码是否可执行
• ✅ 参数说明是否准确
• ✅ 错误处理是否覆盖完整

📝 接口开发标准流程

步骤 1: 接口设计

1. 确定接口功能和规范
2. 设计请求/响应格式
3. 评估安全性和性能影响

步骤 2: 文档先行

⚠️ 在编写代码前，必须先创建API文档

1. 创建接口文档（按照标准模板）
2. 团队review文档设计
3. 确认文档格式符合规范

步骤 3: 代码实现

1. 按照文档规范实现接口
2. 确保代码与文档一致
3. 实现完整的错误处理

步骤 4: 测试验证

1. 功能测试（按文档示例）
2. 边界条件测试
3. 错误场景测试

步骤 5: 文档更新

1. 根据实际实现更新文档
2. 补充实际测试的示例
3. 添加遇到的问题和解决方案

🎯 接口文档标准模板

创建 API_TEMPLATE.md 作为标准模板：

# {接口名称} API 接口文档

## 接口信息

POST/GET/PUT/DELETE /api/{路径}

## 功能描述
{详细描述接口的功能和用途}

## 请求参数
```json
{
  "param1": "value1",    // 参数说明
  "param2": "value2"     // 参数说明
}

参数说明

参数名	类型	必填	默认值	说明
param1	string	✅	-	参数1的详细说明
param2	number	否	0	参数2的详细说明

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "操作成功",
  "data": {
    "result": "响应数据"
  }
}

错误响应 (4xx/5xx)

{
  "status": "error",
  "message": "错误信息",
  "error": "详细错误描述"
}

使用示例

cURL 示例

curl -X POST https://jy-api.fyshark.com/api/{路径} \
  -H "Content-Type: application/json" \
  -d '{
    "param1": "test",
    "param2": 123
  }'

JavaScript 示例

const response = await fetch('/api/{路径}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    param1: 'test',
    param2: 123
  })
});

const result = await response.json();
console.log(result);

错误码说明

错误码	错误信息	说明	解决方案
400	参数错误	请求参数不正确	检查参数格式和类型
401	未授权	需要登录或权限不足	提供有效的认证信息

注意事项

1. {重要提示1}
2. {重要提示2}

更新日志

• v1.0.0 (YYYY-MM-DD): 初始版本

## 🔧 工具和自动化

### 文档生成脚本
创建自动化脚本来简化文档创建过程：

```bash
# scripts/create-api-doc.sh
#!/bin/bash

API_NAME=$1
if [ -z "$API_NAME" ]; then
    echo "用法: ./create-api-doc.sh <接口名称>"
    exit 1
fi

DOC_FILE="API_${API_NAME^^}.md"

if [ -f "$DOC_FILE" ]; then
    echo "⚠️  文档已存在: $DOC_FILE"
    exit 1
fi

# 复制模板并替换占位符
cp API_TEMPLATE.md "$DOC_FILE"
sed -i "s/{接口名称}/$API_NAME/g" "$DOC_FILE"
sed -i "s/{路径}/$(echo $API_NAME | tr '[:upper:]' '[:lower:]')/g" "$DOC_FILE"

echo "✅ 已创建API文档: $DOC_FILE"
echo "📝 请编辑文档内容完善接口说明"

Git Hook 检查

在 .git/hooks/pre-commit 中添加文档检查：

#!/bin/bash
# 检查新增的接口是否有对应文档

# 检查是否有新增的路由文件
NEW_ROUTES=$(git diff --cached --name-only | grep "routes/.*\.js$")

if [ ! -z "$NEW_ROUTES" ]; then
    echo "检查新增路由的API文档..."
    
    # 这里可以添加更复杂的检查逻辑
    # 比如解析路由文件，检查对应的API文档是否存在
    
    echo "✅ API文档检查通过"
fi

📚 文档管理规范

版本控制

1. API文档与代码同步提交
2. 文档变更必须在commit message中说明
3. 重大接口变更需要升级文档版本号

文档审查

1. 新接口文档需要至少1人review
2. 文档变更需要相关团队成员确认
3. 定期检查文档与实际接口的一致性

文档维护

1. 每月检查文档的时效性
2. 及时更新过期的示例和链接
3. 收集用户反馈并改进文档质量

🏆 最佳实践

DO ✅

• 在编写代码前先写文档
• 提供完整可运行的示例
• 包含详细的错误处理说明
• 定期更新和维护文档
• 使用统一的格式和风格

DON'T ❌

• 不要在没有文档的情况下发布接口
• 不要提供过时或错误的示例
• 不要忽略错误场景的文档
• 不要使用模糊或不清楚的描述
• 不要让文档与实际实现不一致

📋 检查清单

在发布新接口前，请确认以下检查项：

文档完整性检查

• 接口信息描述清楚
• 参数表格完整准确
• 响应格式详细说明
• 提供至少2种语言的示例
• 错误处理覆盖完整
• 注意事项说明充分

质量检查

• 示例代码可以直接运行
• 参数类型和格式正确
• 错误码和消息准确
• 文档格式符合规范
• 无拼写和语法错误

一致性检查

• 文档与代码实现一致
• 接口行为与文档描述一致
• 错误处理与文档说明一致
• 参数验证与文档要求一致

🎯 执行和监督

团队责任

• 开发者: 必须为自己开发的接口编写文档
• Code Reviewer: 必须检查接口文档的完整性
• 项目负责人: 定期检查文档质量和维护情况

违规处理

1. 第一次违规: 提醒并要求补充文档
2. 重复违规: 代码review不通过，必须补充文档后重新提交
3. 严重违规: 团队内部分享经验，改进流程

📞 支持和反馈

如有关于文档规范的问题或建议，请：

1. 在项目issue中提出
2. 在团队会议中讨论
3. 直接联系项目负责人

---

记住：好的API文档是用户体验的重要组成部分，也是项目可维护性的关键因素！ 📖✨