Fizzy 导出 API 实战指南账户导出与个人数据导出的异步作业、状态轮询与文件过期机制【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzy导出Exports是 Fizzy 中用于将账户数据或个人用户数据打包下载的功能。本篇指南基于 docs/api/sections/exports.md 展开完整覆盖账户导出与个人数据导出两类异步 API 的端点、状态机、轮询策略与下载链接语义并结合仓库源码控制器、模型、后台作业与视图剖析其底层实现帮助你在集成脚本或 Bot 中正确、稳健地使用导出能力。导出机制概览异步作业 状态轮询导出不是一个同步返回文件的操作而是异步作业asynchronous job。调用方先以POST发起导出请求随后用GET轮询导出资源直到其状态变为completed文件就绪后响应中会携带一个临时的download_url。导出状态共有四种状态含义pending已创建导出记录等待后台作业拾取processing后台作业正在打包数据zip 正在生成completed打包完成文件已附加download_url可用failed打包过程中出现异常作业失败这四种状态与模型层定义完全对应在 app/models/export.rb 中通过enum :status, %w[ pending processing completed failed ]声明默认值为pendingbuild方法先调用processing!将记录置为处理中成功后mark_completed置为completed异常则update!(status: :failed)并重新抛出异常。关键约束完成后的导出文件24 小时后过期。过期后必须重新发起一次新的导出请求。过期逻辑同样有源码支撑——模型中的currentscope 限定为created_at在过去 24 小时内expiredscope 则为completed_at早于 24 小时前的记录并提供cleanup类方法批量销毁过期记录。账户导出POST /:account_slug/account/exports发起当前账户account的完整数据导出。只有账户管理员admin和所有者owner可以创建账户导出。POST /:account_slug/account/exports成功响应201 Created返回导出对象{ id: 03f8huu0sog76g3s97596abcd, status: pending, created_at: 2026-04-02T12:34:56Z }对应的路由声明在 config/routes.rb 中resources :exports, only: [ :create, :show ]位于账户命名空间下。控制器实现见 app/controllers/account/exports_controller.rb权限校验before_action :ensure_admin_or_owner若当前用户既非 admin 也非 owner直接返回403 Forbidden并发限制before_action :ensure_export_limit_not_exceeded当Current.account.exports.current.count CURRENT_EXPORT_LIMIT常量为 10时返回429 Too Many Requests即同一账户同时最多保留 10 个 24 小时内的有效导出创建流程Current.account.exports.create!(user: Current.user)创建记录后立即调用export.build_later投递后台作业随后返回201 Created支持 HTML 与 JSON 两种格式HTML 请求会重定向到账户设置页并闪现提示信息JSON 请求则渲染show模板。查询账户导出状态GET /:account_slug/account/exports/:id返回由当前用户创建的账户导出的状态。GET /:account_slug/account/exports/:id成功响应{ id: 03f8huu0sog76g3s97596abcd, status: completed, created_at: 2026-04-02T12:34:56Z, download_url: https://app.fizzy.do/rails/active_storage/blobs/redirect/.../fizzy-account-export.zip }download_url字段仅在导出完成且文件仍可访问时出现。这一点在 JSON 模板中有直接实现查看 app/views/account/exports/show.json.jbuilder 与 app/views/users/data_exports/show.json.jbuilder两者逻辑一致——只有export.completed? export.file.attached?同时满足时才输出download_url且通过rails_blob_url(export.file, disposition: attachment)生成 Active Storage 重定向链接disposition: attachment强制浏览器以下载而非内嵌方式处理。下载鉴权download_url指向的下载请求仍然需要导出所有者export owner的正常认证访问不能脱离会话或令牌直接匿名下载。控制器层也做了归属校验账户导出的set_export使用find_by(id: params[:id], user: Current.user)确保只能查询到自己的导出。个人数据导出POST /:account_slug/users/:user_id/data_exports发起当前用户的个人数据导出。你只能为自己的用户记录创建导出不能替其他用户发起。POST /:account_slug/users/:user_id/data_exports成功响应201 Created返回导出对象{ id: 03f8huu0sog76g3s97596wxyz, status: pending, created_at: 2026-04-02T12:34:56Z }路由同样在 config/routes.rb 中声明resources :data_exports, only: [ :create, :show ]。控制器实现见 app/controllers/users/data_exports_controller.rb归属校验set_user通过Current.account.users.find(params[:user_id])解析目标用户限定在当前账户内ensure_current_user要求user Current.user否则返回403 Forbidden并发限制与账户导出一致CURRENT_EXPORT_LIMIT 10超出返回429 Too Many Requests创建流程user.data_exports.create!(account: Current.account)后调用build_later投递后台作业。查询个人数据导出状态GET /:account_slug/users/:user_id/data_exports/:id返回你的个人数据导出中某一个的状态。GET /:account_slug/users/:user_id/data_exports/:id成功响应{ id: 03f8huu0sog76g3s97596wxyz, status: completed, created_at: 2026-04-02T12:34:56Z, download_url: https://app.fizzy.do/rails/active_storage/blobs/redirect/.../fizzy-user-data-export.zip }与账户导出相同download_url仅在completed且文件仍可用时出现下载仍需导出所有者的认证。注意个人数据导出的set_export不额外过滤useruser.data_exports.find_by(id: params[:id])因为用户解析本身就限定在Current.account.users中并且ensure_current_user已保证只能访问自己的导出。源码级原理导出如何从pending走到completed状态机与生命周期app/models/export.rbExport是两类导出的共同基类Account::Export与User::DataExport的父类核心链路如下控制器创建记录默认状态pending并调用build_laterbuild_later调用DataExportJob.perform_later(self)投递异步作业作业定义见 app/jobs/data_export_job.rb队列为:backend并通过discard_on ActiveJob::DeserializationError优雅丢弃无法反序列化的过期作业作业执行export.build先将状态置为processing!在with_context中临时设定Current.account与ActiveStorage::Current.url_options确保导出内容里的附件 URL 使用默认路由选项生成随后通过ZipFile.create_for(file, filename: filename)创建 zip 附件并调用子类实现的populate_zip填充内容完成后mark_completed写入completed_at并投递ExportMailer.completed(self)通知邮件任一步骤抛异常则更新状态为failed并继续抛出交由作业框架处理。两种导出类型的内容差异账户导出app/models/account/export.rb文件名形如fizzy-account-account_id-export-id.zip内容通过Account::DataTransfer::Manifest.new(account)枚举账户的全部 record set账户、用户、富文本、Active Storage 附件/Blob 等见 app/models/account/data_transfer 目录下的record_set.rb及各子类逐个record_set.export(to: zip)写入 zip个人数据导出文件名形如fizzy-user-data-export.zip文档示例同样复用Export#build的 zip 打包与邮件通知链路。过期与清理Export.currentscope 覆盖 24 小时内的有效导出既是并发限制的计数依据也是download_url有效期的来源Export.expiredscope 对应已过期的导出Export.cleanup会批量销毁它们。文档强调的完成文件 24 小时后过期、需重新发起导出正是由这套 scope 与清理逻辑共同保证的。实战用 curl 发起并轮询一次账户导出结合 API 文档与上述实现一次完整的集成流程如下省略鉴权头认证方式见 docs/api/sections/authentication.md例如个人访问令牌# 1. 发起导出拿到导出 id curl -X POST \ -H Authorization: Bearer token \ -H Accept: application/json \ https://app.fizzy.do/account_slug/account/exports # 2. 轮询导出状态pending - processing - completed curl -H Authorization: Bearer token \ -H Accept: application/json \ https://app.fizzy.do/account_slug/account/exports/export_id # 3. 状态为 completed 后用响应中的 download_url 下载 curl -L -o export.zip \ -H Authorization: Bearer token \ https://app.fizzy.do/rails/active_storage/blobs/redirect/...轮询建议采用带间隔的循环例如每 510 秒请求一次GET直到status变为completed或failed若收到failed应检查输入数据并重新发起。个人数据导出的调用方式相同仅路径换为/users/:user_id/data_exports。实践要点与限制权限账户导出仅限账户 admin / owner个人数据导出仅限本人。越权访问返回403。并发上限两类导出各自限制同一作用域下 24 小时内最多 10 个有效导出超出返回429 Too Many Requests。轮询期间旧的completed导出会持续占用名额注意及时下载并在不需要时让其自然过期。下载时效download_url是临时链接与导出文件一同在 24 小时后过期过期后需重新发起新导出。下载鉴权即使拿到download_url下载时仍需以导出所有者的身份完成认证。结果通知导出完成后系统会向导出所有者发送完成邮件ExportMailer.completed可作为轮询之外的补充信号。失败的导出异常会导致状态置为failed不会生成可下载文件download_url也不会出现在响应中。如需了解导出 API 在整个 Fizzy API 体系中的位置可参考 docs/api/README.md若要深入 zip 打包实现可阅读 app/models/zip_file.rb 与账户数据清单 app/models/account/data_transfer/manifest.rb。【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Fizzy 导出 API 实战指南：账户导出与个人数据导出的异步作业、状态轮询与文件过期机制
Fizzy 导出 API 实战指南账户导出与个人数据导出的异步作业、状态轮询与文件过期机制【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzy导出Exports是 Fizzy 中用于将账户数据或个人用户数据打包下载的功能。本篇指南基于 docs/api/sections/exports.md 展开完整覆盖账户导出与个人数据导出两类异步 API 的端点、状态机、轮询策略与下载链接语义并结合仓库源码控制器、模型、后台作业与视图剖析其底层实现帮助你在集成脚本或 Bot 中正确、稳健地使用导出能力。导出机制概览异步作业 状态轮询导出不是一个同步返回文件的操作而是异步作业asynchronous job。调用方先以POST发起导出请求随后用GET轮询导出资源直到其状态变为completed文件就绪后响应中会携带一个临时的download_url。导出状态共有四种状态含义pending已创建导出记录等待后台作业拾取processing后台作业正在打包数据zip 正在生成completed打包完成文件已附加download_url可用failed打包过程中出现异常作业失败这四种状态与模型层定义完全对应在 app/models/export.rb 中通过enum :status, %w[ pending processing completed failed ]声明默认值为pendingbuild方法先调用processing!将记录置为处理中成功后mark_completed置为completed异常则update!(status: :failed)并重新抛出异常。关键约束完成后的导出文件24 小时后过期。过期后必须重新发起一次新的导出请求。过期逻辑同样有源码支撑——模型中的currentscope 限定为created_at在过去 24 小时内expiredscope 则为completed_at早于 24 小时前的记录并提供cleanup类方法批量销毁过期记录。账户导出POST /:account_slug/account/exports发起当前账户account的完整数据导出。只有账户管理员admin和所有者owner可以创建账户导出。POST /:account_slug/account/exports成功响应201 Created返回导出对象{ id: 03f8huu0sog76g3s97596abcd, status: pending, created_at: 2026-04-02T12:34:56Z }对应的路由声明在 config/routes.rb 中resources :exports, only: [ :create, :show ]位于账户命名空间下。控制器实现见 app/controllers/account/exports_controller.rb权限校验before_action :ensure_admin_or_owner若当前用户既非 admin 也非 owner直接返回403 Forbidden并发限制before_action :ensure_export_limit_not_exceeded当Current.account.exports.current.count CURRENT_EXPORT_LIMIT常量为 10时返回429 Too Many Requests即同一账户同时最多保留 10 个 24 小时内的有效导出创建流程Current.account.exports.create!(user: Current.user)创建记录后立即调用export.build_later投递后台作业随后返回201 Created支持 HTML 与 JSON 两种格式HTML 请求会重定向到账户设置页并闪现提示信息JSON 请求则渲染show模板。查询账户导出状态GET /:account_slug/account/exports/:id返回由当前用户创建的账户导出的状态。GET /:account_slug/account/exports/:id成功响应{ id: 03f8huu0sog76g3s97596abcd, status: completed, created_at: 2026-04-02T12:34:56Z, download_url: https://app.fizzy.do/rails/active_storage/blobs/redirect/.../fizzy-account-export.zip }download_url字段仅在导出完成且文件仍可访问时出现。这一点在 JSON 模板中有直接实现查看 app/views/account/exports/show.json.jbuilder 与 app/views/users/data_exports/show.json.jbuilder两者逻辑一致——只有export.completed? export.file.attached?同时满足时才输出download_url且通过rails_blob_url(export.file, disposition: attachment)生成 Active Storage 重定向链接disposition: attachment强制浏览器以下载而非内嵌方式处理。下载鉴权download_url指向的下载请求仍然需要导出所有者export owner的正常认证访问不能脱离会话或令牌直接匿名下载。控制器层也做了归属校验账户导出的set_export使用find_by(id: params[:id], user: Current.user)确保只能查询到自己的导出。个人数据导出POST /:account_slug/users/:user_id/data_exports发起当前用户的个人数据导出。你只能为自己的用户记录创建导出不能替其他用户发起。POST /:account_slug/users/:user_id/data_exports成功响应201 Created返回导出对象{ id: 03f8huu0sog76g3s97596wxyz, status: pending, created_at: 2026-04-02T12:34:56Z }路由同样在 config/routes.rb 中声明resources :data_exports, only: [ :create, :show ]。控制器实现见 app/controllers/users/data_exports_controller.rb归属校验set_user通过Current.account.users.find(params[:user_id])解析目标用户限定在当前账户内ensure_current_user要求user Current.user否则返回403 Forbidden并发限制与账户导出一致CURRENT_EXPORT_LIMIT 10超出返回429 Too Many Requests创建流程user.data_exports.create!(account: Current.account)后调用build_later投递后台作业。查询个人数据导出状态GET /:account_slug/users/:user_id/data_exports/:id返回你的个人数据导出中某一个的状态。GET /:account_slug/users/:user_id/data_exports/:id成功响应{ id: 03f8huu0sog76g3s97596wxyz, status: completed, created_at: 2026-04-02T12:34:56Z, download_url: https://app.fizzy.do/rails/active_storage/blobs/redirect/.../fizzy-user-data-export.zip }与账户导出相同download_url仅在completed且文件仍可用时出现下载仍需导出所有者的认证。注意个人数据导出的set_export不额外过滤useruser.data_exports.find_by(id: params[:id])因为用户解析本身就限定在Current.account.users中并且ensure_current_user已保证只能访问自己的导出。源码级原理导出如何从pending走到completed状态机与生命周期app/models/export.rbExport是两类导出的共同基类Account::Export与User::DataExport的父类核心链路如下控制器创建记录默认状态pending并调用build_laterbuild_later调用DataExportJob.perform_later(self)投递异步作业作业定义见 app/jobs/data_export_job.rb队列为:backend并通过discard_on ActiveJob::DeserializationError优雅丢弃无法反序列化的过期作业作业执行export.build先将状态置为processing!在with_context中临时设定Current.account与ActiveStorage::Current.url_options确保导出内容里的附件 URL 使用默认路由选项生成随后通过ZipFile.create_for(file, filename: filename)创建 zip 附件并调用子类实现的populate_zip填充内容完成后mark_completed写入completed_at并投递ExportMailer.completed(self)通知邮件任一步骤抛异常则更新状态为failed并继续抛出交由作业框架处理。两种导出类型的内容差异账户导出app/models/account/export.rb文件名形如fizzy-account-account_id-export-id.zip内容通过Account::DataTransfer::Manifest.new(account)枚举账户的全部 record set账户、用户、富文本、Active Storage 附件/Blob 等见 app/models/account/data_transfer 目录下的record_set.rb及各子类逐个record_set.export(to: zip)写入 zip个人数据导出文件名形如fizzy-user-data-export.zip文档示例同样复用Export#build的 zip 打包与邮件通知链路。过期与清理Export.currentscope 覆盖 24 小时内的有效导出既是并发限制的计数依据也是download_url有效期的来源Export.expiredscope 对应已过期的导出Export.cleanup会批量销毁它们。文档强调的完成文件 24 小时后过期、需重新发起导出正是由这套 scope 与清理逻辑共同保证的。实战用 curl 发起并轮询一次账户导出结合 API 文档与上述实现一次完整的集成流程如下省略鉴权头认证方式见 docs/api/sections/authentication.md例如个人访问令牌# 1. 发起导出拿到导出 id curl -X POST \ -H Authorization: Bearer token \ -H Accept: application/json \ https://app.fizzy.do/account_slug/account/exports # 2. 轮询导出状态pending - processing - completed curl -H Authorization: Bearer token \ -H Accept: application/json \ https://app.fizzy.do/account_slug/account/exports/export_id # 3. 状态为 completed 后用响应中的 download_url 下载 curl -L -o export.zip \ -H Authorization: Bearer token \ https://app.fizzy.do/rails/active_storage/blobs/redirect/...轮询建议采用带间隔的循环例如每 510 秒请求一次GET直到status变为completed或failed若收到failed应检查输入数据并重新发起。个人数据导出的调用方式相同仅路径换为/users/:user_id/data_exports。实践要点与限制权限账户导出仅限账户 admin / owner个人数据导出仅限本人。越权访问返回403。并发上限两类导出各自限制同一作用域下 24 小时内最多 10 个有效导出超出返回429 Too Many Requests。轮询期间旧的completed导出会持续占用名额注意及时下载并在不需要时让其自然过期。下载时效download_url是临时链接与导出文件一同在 24 小时后过期过期后需重新发起新导出。下载鉴权即使拿到download_url下载时仍需以导出所有者的身份完成认证。结果通知导出完成后系统会向导出所有者发送完成邮件ExportMailer.completed可作为轮询之外的补充信号。失败的导出异常会导致状态置为failed不会生成可下载文件download_url也不会出现在响应中。如需了解导出 API 在整个 Fizzy API 体系中的位置可参考 docs/api/README.md若要深入 zip 打包实现可阅读 app/models/zip_file.rb 与账户数据清单 app/models/account/data_transfer/manifest.rb。【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考