概述

本文档详细说明了如何将秋名社账号认证系统接入您的应用，实现用户使用秋名社账号登录功能。接入过程分为前端授权请求和后端用户信息获取两个部分。

接入流程概览

sequenceDiagram participant User participant YourApp as 您的应用 participant AkinaClub as 秋名社认证系统 User->>YourApp: 点击登录按钮 YourApp->>AkinaClub: 重定向到认证页面(appid参数) AkinaClub->>User: 显示登录/授权页面 User->>AkinaClub: 输入账号密码并授权 AkinaClub->>YourApp: 重定向到回调地址(附带code) YourApp->>AkinaClub: 使用code请求用户信息 AkinaClub->>YourApp: 返回用户JSON数据 YourApp->>User: 登录成功，显示用户信息

前端接入指南

在您的应用登录页面放置秋名社登录按钮，链接格式如下：

HTML<a href="https://www.kish.top/login.html?appid=YOUR_APP_ID&msg=YOUR_APP_MSG" 
   class="akina-login-btn">
    <img src="https://static.codemao.cn/pickduck/BkCDTvodgl.png" alt="秋名社登录">
    使用秋名社账号登录
</a>

参数说明：

  • appid: 您在秋名社开发者平台申请的应用ID（必填）
  • msg: 需要客户端向后端传递的信息（选填）

2. 处理回调

用户授权后，秋名社会重定向到您的回调地址，并在URL中附加code参数：

URL格式https://your-domain.com/callback?code=AUTHORIZATION_CODE

前端处理示例代码：

JavaScript// 从URL中获取授权码
const urlParams = new URLSearchParams(window.location.search);
const authCode = urlParams.get('code');

if (authCode) {
    // 将code发送给后端处理
    fetch('/api/akina-auth', {
        method: 'POST',
        body: JSON.stringify({ code: authCode }),
        headers: {
            'Content-Type': 'application/json'
        }
    })
    .then(response => response.json())
    .then(data => {
        // 处理登录成功逻辑
        console.log('登录用户:', data.username);
        // 跳转到用户主页...
    });
}

注意： 授权码(code)的有效期仅为2分钟，请确保及时处理

后端接入指南

1. 接收授权码

后端需要提供回调地址对应的接口，接收GET请求中的code参数

示例路由（Node.js/Express）：

Node.jsapp.get('/auth/callback', (req, res) => {
    const authCode = req.query.code;
    
    if (!authCode) {
        return res.status(400).json({ error: '缺少授权码' });
    }
    
    // 下一步：使用code获取用户信息
});

2. 获取用户信息

使用收到的code请求秋名社API获取用户完整信息

API端点：

API请求GET https://www.kish.top/api/code/{code}

请求示例（Node.js）：

Node.jsconst axios = require('axios');

async function getAkinaUserData(code) {
    try {
        const response = await axios.get(
            `http://www.kish.top/api/code/${code}`
        );
        
        return response.data;
    } catch (error) {
        console.error('获取用户信息失败:', error.response.data);
        throw new Error('认证服务不可用');
    }
}

// 在回调处理中使用
app.get('/auth/callback', async (req, res) => {
    const authCode = req.query.code;
    
    try {
        const userData = await getAkinaUserData(authCode);
        
        // 在此处处理用户登录/注册逻辑
        // 示例：创建会话、返回用户信息等
        
        res.json({
            status: 'success',
            user: userData
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

3. 用户信息响应格式

成功请求将返回JSON格式的用户数据：

JSON响应{
  "authorized_apps": [
    "您的应用名称"
  ],
  "created_at": "2023-01-15 08:30:45",
  "email": "user@example.com",
  "id": 123456,
  "msg": "abc",
  "username": "秋名山车神"
}
字段名 类型 说明
authorized_apps string[] 用户已授权的应用列表
created_at string 用户在秋名社的注册时间
id integer 用户的秋名社唯一ID
msg string 客户端向后端传递的信息
username string 用户在秋名社的用户名

错误处理

常见错误情况

无效的授权码

响应： HTTP 400

原因： code参数无效或已过期

应用未授权

响应： HTTP 403

原因： 用户未授权该应用

服务器错误

响应： HTTP 500

原因： 秋名社服务器内部错误

错误响应示例

JSON错误响应{
  "error": "invalid_code",
  "error_description": "授权码无效或已过期"
}

State参数使用示例

JavaScript// 生成随机state
const state = Math.random().toString(36).substring(2, 15);

// 存储到session
sessionStorage.setItem('akina_state', state);

// 添加到认证链接
const authUrl = `https://www.kish.top/auth.html?appid=APP_ID&state=${state}`;

// 回调时验证
const urlParams = new URLSearchParams(window.location.search);
const stateParam = urlParams.get('state');
const savedState = sessionStorage.getItem('akina_state');

if (stateParam !== savedState) {
    // 防止CSRF攻击
    console.error('State参数不匹配');
    return;
}

常见问题解答

如何申请应用ID？

访问秋名社开发者平台（developer.kish.top）注册开发者账号并创建应用（正在内测中）

授权码有效期多久？

每个授权码(code)有效期为2分钟，且只能使用一次

支持哪些HTTP方法？

所有API端点均支持GET方法

是否有请求频率限制？

每个appid每分钟最多允许100次请求

技术支持

如有任何接入问题，请联系秋名社开发者支持团队

邮箱支持 开发者论坛 访问官网

我们将在24小时内回复您的问题