小僵尸论坛 API 开发文档

本文档详细介绍了如何通过 API 接口获取 Discuz! 用户的头像，方便在其他系统或应用中集成用户头像显示功能。

一、API 调用地址

API 请求地址：

https://www.zitbbs.com/get_avatar.php?uid=用户UID&size=头像尺寸

参数说明：

二、返回结果

直接返回用户头像的图片数据，内容类型为 image/jpeg。如果用户未设置头像或出现错误，则返回默认头像。

三、使用示例

1. 获取 UID 为 12345 的用户中等尺寸头像

https://www.zitbbs.com/get_avatar.php?uid=12345

2. 获取 UID 为 67890 的用户大尺寸头像

https://www.zitbbs.com/get_avatar.php?uid=67890&size=big

3. 在 HTML 中显示用户头像

可以在 HTML 中使用 <img> 标签直接引用：

<img src="https://www.zitbbs.com/get_avatar.php?uid=12345&size=small" alt="用户头像">

四、注意事项

1. 参数校验：请确保传递的 uid 为有效的用户 ID，size 参数仅支持指定的三个值。
2. 缓存处理：API 已设置浏览器缓存头，客户端可适当缓存头像以减少请求次数。
3. 错误处理：如果请求的用户不存在或未设置头像，API 将返回默认头像。
4. 请求频率：请避免频繁请求，以免给服务器带来过大压力。
5. 版权声明：头像内容仅限于合理使用，请遵守相关法律法规。

五、常见问题

1. 为什么获取的头像不是最新的？

可能是因为浏览器缓存了旧的头像。可以在请求地址后添加随机参数以避免缓存：

https://www.zitbbs.com/get_avatar.php?uid=12345&size=big&_t=时间戳

2. 如何获取默认头像？

当用户未设置头像时，API 会自动返回默认头像，无需额外处理。

六、技术实现说明

API 的内部实现主要根据用户 UID 计算头像的存储路径，然后返回对应的头像文件。

头像路径计算方式：

1. 将 UID 格式化为 9 位数字，前面补零，例如 UID 为 12345，格式化后为 000012345。
2. 目录结构：
• dir1：取前 3 位，例如 000。
• dir2：取第 4-5 位，例如 01。
• dir3：取第 6-7 位，例如 23。
3. 文件名：取最后 2 位作为文件名的一部分，例如 45，文件名格式为 45_avatar_middle.jpg。
4. 完整路径：

/uc_server/data/avatar/{dir1}/{dir2}/{dir3}/{uid_sub}_avatar_{size}.jpg

示例：

对于 UID 为 12345 的用户：

• 格式化后 UID：000012345
• dir1：000
• dir2：01
• dir3：23
• uid_sub：45
• 头像文件名：45_avatar_middle.jpg
• 完整路径：

/uc_server/data/avatar/000/01/23/45_avatar_middle.jpg

七、联系方式

如有任何疑问或建议，请联系网站管理员。

八、版本更新

• v1.0 - 初始版本，实现基本的头像获取功能。