C# MVC API 客户端登录接口文档

📋 接口概述

接口名称: 客户端登录
接口路径: /api/controller/client-login
请求方法: POST
认证方式: API Key验证 + 用户名密码验证

---

🛠️ 接口代码

[HttpPost("client-login")]
public async Task<IActionResult> ClientLogin([FromBody] ClientLoginRequest request)
{
    // 验证API_KEY
    var apiKeyHeader = Request.Headers["X-Api-Key"].FirstOrDefault();
    var expectedApiKey = _configuration["ClientConnectApi:ApiKey"];

    if (string.IsNullOrEmpty(apiKeyHeader) || apiKeyHeader != expectedApiKey)
    {
        return Unauthorized(new ClientLoginResponse
        {
            Success = false,
            UserGuid = string.Empty,
            Message = "无效的API密钥"
        });
    }

    if (string.IsNullOrEmpty(request.Identifier) || string.IsNullOrEmpty(request.Password))
    {
        return BadRequest(new ClientLoginResponse
        {
            Success = false,
            UserGuid = string.Empty,
            Message = "标识符和密码不能为空"
        });
    }

    try
    {
        // 创建UserManager实例用于验证用户
        var userManager = new UserManager(_db);

        // 验证用户（支持用户名、电话或邮箱）
        // ... 具体验证逻辑
    }
    catch (Exception ex)
    {
        // 异常处理
    }
}

---

🔑 请求参数

请求头 (Headers)

参数名	类型	必填	说明
Content-Type	string	是	必须为 application/json
X-Api-Key	string	是	API密钥，从配置中获取

请求体 (Body - JSON格式)

{
    "Identifier": "string",  // 用户名、电话或邮箱
    "Password": "string"     // 用户密码
}

---

📤 响应格式

成功响应示例

{
    "Success": true,
    "UserGuid": "用户唯一标识符",
    "Message": "登录成功"
}

失败响应示例

{
    "Success": false,
    "UserGuid": "",
    "Message": "错误信息描述"
}

---

🔧 CURL 测试方法

1. 基本测试命令

curl -X POST "https://your-domain.com/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-value" \
  -d '{
    "Identifier": "your-identifier",
    "Password": "your-password"
  }'

2. 本地开发环境测试

HTTP (端口通常为5000):

curl -X POST "http://localhost:5000/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-from-config" \
  -d '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }'

HTTPS (端口通常为5001, 使用自签名证书):

curl -X POST "https://localhost:5001/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-from-config" \
  -d '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }' \
  --insecure  # 跳过SSL证书验证

3. 带详细信息的测试命令

curl -X POST "http://localhost:5000/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-from-config" \
  -d '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }' \
  -w "\nHTTP Status: %{http_code}\n" \
  -v  # 显示详细请求/响应信息

---

🧪 测试场景示例

场景1: 缺少API Key

curl -X POST "http://localhost:5000/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -d '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }'

预期响应: HTTP 401 Unauthorized

场景2: API Key错误

curl -X POST "http://localhost:5000/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: wrong-api-key" \
  -d '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }'

预期响应: HTTP 401 Unauthorized

场景3: 参数为空

curl -X POST "http://localhost:5000/api/controller/client-login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-from-config" \
  -d '{
    "Identifier": "",
    "Password": ""
  }'

预期响应: HTTP 400 Bad Request

---

🪟 Windows PowerShell 测试

curl.exe -Method POST `
  -Uri "http://localhost:5000/api/controller/client-login" `
  -Headers @{
    "Content-Type" = "application/json"
    "X-Api-Key" = "your-api-key-from-config"
  } `
  -Body '{
    "Identifier": "testuser@example.com",
    "Password": "password123"
  }'

---

🖥️ GUI工具测试指南

Postman 配置:

• Method: POST
• URL: http://localhost:5000/api/controller/client-login
• Headers:
• Content-Type: application/json
• X-Api-Key: your-api-key-from-config
• Body (raw JSON): json { "Identifier": "testuser@example.com", "Password": "password123" }

---

📝 注意事项

1. API Key获取: 从 appsettings.json 配置文件中的 ClientConnectApi:ApiKey 节点获取
2. 路由配置: 确保URL中的控制器路径与实际路由一致
3. 端口配置: 根据开发环境调整端口号（5000/5001或其他）
4. Identifier格式: 支持用户名、电话或邮箱，具体取决于 UserManager 实现
5. SSL证书: 开发环境使用自签名证书时，需要添加 --insecure 参数跳过验证

---

🔒 安全建议

1. API Key管理:
2. 不要将API Key硬编码在客户端
3. 使用环境变量或安全的配置管理

4. 定期轮换API Key

5. 传输安全:

6. 生产环境必须使用HTTPS

7. 确保密码在传输过程中加密

8. 输入验证:

9. 对 Identifier 和 Password 进行格式验证
10. 实施防暴力破解机制（如登录尝试限制）

---

文档生成时间: 2025年12月1日
最后更新: 2025年12月1日

---

related: - [[API响应JSON数据解析的Python实现文档]] - [[aspdotnet_core_mvc_api_开发与调用规范文档]]

---