请求标头

Headers 参数

参数名	类型	是否必传	说明
X-Fresns-App-Id	String	YES	密钥 App ID 密钥位置：`控制面板->应用中心->应用密钥`
X-Fresns-Client-Platform-Id	Number	YES	平台编号，与密钥的「平台」匹配密钥位置：`控制面板->应用中心->应用密钥` 查看平台对应的 ID 编号
X-Fresns-Client-Version	String	YES	你的客户端版本号，推荐使用语义化版本号
X-Fresns-Client-Device-Info	String	YES	交互设备信息 `session_logs > device_info` 压缩 Object 信息为字符串传参
X-Fresns-Client-Lang-Tag	String	NO	客户端的语言标签（留空则输出默认语言）配置位置：`控制面板->系统->语言设置`
X-Fresns-Client-Timezone	String	NO	UTC 时区（留空则使用默认时区）配置位置：`控制面板->系统->站点设置` 用户登录后，如果留空，则服务端自动以用户配置的时区处理时间格式
X-Fresns-Client-Content-Format	String	NO	内容格式（帖子和评论的列表与详情），留空则原样输出。传参 `html` 将内容转换为 html 格式（文本内容的 `\n` 转换为 `<br/>`，Markdown 内容转换为 `HTML`）
X-Fresns-Aid	String	YES/NO	账号参数（留空则视为未登录账号）
X-Fresns-Aid-Token	String	YES/NO	账号身份凭证（传参 `aid` 时必传）
X-Fresns-Uid	Number	YES/NO	用户参数（留空则视为未登录用户）
X-Fresns-Uid-Token	String	YES/NO	用户身份凭证（传参 `uid` 时必传）
X-Fresns-Signature	String	YES	查看签名生成规则
X-Fresns-Signature-Timestamp	String	YES	签名生成时间（当前 Unix 时间戳，精确到秒或毫秒都支持）

注册和登录流程

开始

注册或登录成功后，获取账号凭证

aid: data.detail.aid

aidToken: data.sessionToken.token

判断账号名下用户数 data.detail.users

1 个

2 个及以上 呈现「选择用户」视图

判断是否有密码 data.detail.users.hasPassword

无密码

有密码 呈现「密码输入框」视图

登录用户

/api/v2/user/auth

用户登录成功后，获取用户凭证

uid: data.detail.uid

uidToken: data.sessionToken.token

结束

当账号名下只有 1 个用户，并且无密码，建议直接让用户无感知的登录成功。

运行模式介绍

配置表键名 site_mode

公开模式，键值为 public

私有模式，键值为 private

获取方法 /api/v2/global/configs?keys=site_mode

每个接口的介绍页都有两种模式的账号和用户参数是否必传说明。

aid 必传，表示必须登录账号才能请求该接口，此时 token 参数为账号的 token

uid 必传时，aid 也必传，表示必须登录「账号的用户」才能请求该接口，此时 token 参数为用户的 token

签名生成规则

PHP 可引用封装方法 App\Helpers\SignHelper::makeSign($signMap, $appSecret)

其他客户端请参考下方流程：

1、提取参与签名的 headers 参数

// 未登录
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

// 已登录账号
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

// 已登录用户
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Uid": 782622,
    "X-Fresns-Uid-Token": "PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

2、以参数名按照 ASCII 码从小到大排序（字典序）

{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Uid": 782622,
    "X-Fresns-Uid-Token": "PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

3、对排序后的新参数使用 URL 键值对的格式拼接成字符串。

X-Fresns-Aid=wIfu6jaF&X-Fresns-Aid-Token=uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz&X-Fresns-App-Id=yh1OJ7WL&X-Fresns-Client-Platform-Id=2&X-Fresns-Client-Version=2.0.0&X-Fresns-Signature-Timestamp=1674161913192&X-Fresns-Uid=782622&X-Fresns-Uid-Token=PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c

4、再拼接上 &AppSecret={app_secret} 得到待签名字符串。

X-Fresns-Aid=wIfu6jaF&X-Fresns-Aid-Token=uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz&X-Fresns-App-Id=yh1OJ7WL&X-Fresns-Client-Platform-Id=2&X-Fresns-Client-Version=2.0.0&X-Fresns-Signature-Timestamp=1674161913192&X-Fresns-Uid=782622&X-Fresns-Uid-Token=PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c&AppSecret=qUiEaDNQh2IpvGHOKlTMx7ujn8t1CZWX

5、对签名字符串进行 MD5 运算（32 位小写），得到签名值

2174eaeab76fb6a3790ed4f7ebb2edfb

缓存介绍

我们开发的客户端都采用了全局函数封装，方便全局调用各种配置数据，可参见主题模板标签

fs_api_config('配置键名') 调用 /api/v2/global/configs 接口的参数

fs_lang('语言键名') 调用 fs_api_config('language_pack_contents') 参数

fs_code_message('编号') 调用 /api/v2/global/code-messages 接口的参数

fs_account('参数名') 调用 /api/v2/account/detail 接口的 data 参数

fs_user('参数名') 调用 /api/v2/user/{uidOrUsername}/detail 接口的 data 参数

fs_user_panel('key') 调用 /api/v2/user/panel 接口的 data 参数

其他...

由于全局数据每页都可能用到，为了避免频繁请求接口影响加载速度，所以我们在客户端采用了缓存。

配置项：我们使用 /api/v2/global/configs?keys=cache_datetime,cache_minutes 检测缓存有效期，过期将自动重新缓存。

cache_datetime 服务端最后一次配置的时间。

cache_minutes 建议客户端缓存保存最长分钟数，为空 null 表示不限制。不限制则建议定期请求接口只获取 cache_datetime,cache_minutes 配置，对比有效期是否和本地一致，不一致则表示服务端已经更新配置，请重新缓存。

用户资料：我们建议用户登录后缓存，当用户操作了互动功能，比如点赞、发表、修改资料等操作后，重新再获取用户资料再缓存。

请求标头

请求标头#

Headers 参数#

注册和登录流程#

运行模式介绍#

签名生成规则#

缓存介绍#

请求标头

Headers 参数

注册和登录流程

运行模式介绍

签名生成规则

缓存介绍