作者：BiffLiu
推荐理由
本文从团队工作中遇到的文件处理过程中存在效率痛点出发，利用飞书云文档相关的 OpenAPI 实现了文件的自动导出及格式调整等功能，有力减少了无效耗时。 文章重点介绍了开发的整体过程以及相关 Tips，供大家参考、交流和讨论。
一、关于我们
大家好，我是 BiffLiu，来自字节跳动。目前方向主要为 B 端用户提供准时、精确、安全的资金结算服务，提供了电商各个垂类业务定制化的结算周期和结算方式的能力，保证电商垂类业务的商户、达人、机构享受优质的资金结算服务，促进电商快速增长。
本人 21 年应届毕业于华中科技大学，接触开发工作 4 年，从工业软件到互联网后端，有过 C++、golang 的开发经历，现从事支付域的相关工作。高并发、高可用、高安全、可维护是系统目标，更是自我坚守。日常开发工作中不仅需要关注系统，更需要不断反思工作流，改善工作方式，高效运转。
本 case 是在总结了日常工作流中提炼出的一个小优化，让系统帮助提效，case 虽简单，但提效显著。
二、需求分析
因为电商的结算系统承接了复杂的业务场景，为了保障资金安全、提升系统效率、主动定位系统问题，我们制定了日值班制度（针对前日的结算问题进行跟踪处理）。值班的过程如下图展示：
从流程图中可以看到，真正有效的值班问题处理是从第 7 步，也就是整个流程的最后一步开始的，前面的 1- 6 步主要是在预处理数据，平均估时 15min 左右，属于无效工作。
秉承着 “数据多跑路，释放无效人力” 的原则，我们在想能不能把前面的步骤都自动化，一键生成？
由流程出发，我们分析出值班流程目前存在的痛点有：
a） 预处理步骤只有 1-2 部分实现了自动化，可否全部实现自动化（自动分类，自动导出为完整的一份表格，表格内自动拆分为子表格，不需人工调整），借助强大的计算机算力实现“秒出”？
b） 导出的文件是否可以直接生成飞书 sheet 电子表格，实现一键共享？
针对痛点 a），从程序员的角度出发是完全可以实现的，只需要调整下后台的的生成原始数据的规则，实现自动分类即可；
针对痛点 b），主要涉及到是否可以借助飞书自动化的能力，在数据存储上直接存储为飞书 sheet 格式，对外只表现为一个飞书电子表格的链接，实现共享。效果如下：
250px|700px|reset
总体来看，能否解决以上痛点主要依赖飞书的云文档相关开放能力，于是我们开始调研实现细节。
三、方案调研
飞书目前提供出来的开放能力可以在飞书开放平台官网查看，进入开发文档页面，作为后端需求直接查看服务端文档类目； 从开发文档的目录结构可以看出，文档主要是根据不同的使用场景来进行目录组织的，而我们的需求很明显需要的是[云文档]的能力，Nice！飞书提供了 http 的 RESTFul API 接口，让开发者可以更方便地在后端集成。
根据以上的调研，可初步认定此需求可实现，但由于需求的完成度与细节密切相关，则进一步调研其细节能力，避免出现一个关键的小细节需求影响了整个需求的实现。
注：在 API 调研阶段，需认真调研其能力，并非所有的用户界面操作（日常在飞书 doc 上的操作）均有 API，大家需谨慎调研（例如电子表格提供公式操作，但多维表格暂不提供等）。
为了提升调研效率，本着云文档的操作和日常的本地文档操作基本一致，在此假设上，可按照文档操作经验初步设计导出流程需要的操作，然后一对一调研，是否有完美命中的 api 或者替代 api。初步设想的方案如下：
则可以看到，优化后的工作流的实现主要依赖的能力（或 API）有：
- 创建云表格
- 获取表格元数据（链接，元数据等）
- 文字，链接，邮箱，引用等各种数据类型
- 批量填充数据
- 数据格式调整（加粗，合并单元格等）
- 权限调整相关（提醒并分享给指定值班人员，转移文档所有权）
调研中，作为后端开发，可以感知到作为一个 API 的提供方，需要同步提供包括安全访问，频控，访问权限的说明，这也是一个 API 提供的安全基本保障，则进一步查阅了相关文档，评估了实施可行性，暂无开发 gap。然后就可以开始初步调试接口及进行开发主流程啦！
四、开发流程
1. 新建应用
250px|700px|reset
创建应用主要拿到的信息是应用凭证，类似账号和密码，我理解是开放平台拿到要操作的域信息。
2. 申请权限
为什么要申请权限？不同的操作需要不同的权限 ，有些权限是敏感信息，根据权限最小原则，尽量不要申请敏感权限。 在本需求中在线创建完飞书 sheet 后，需要给值班人员开放编辑权限，针对权限管理的 API 调用需要申请相关的调用权限。
3. 设计最终产出的文档模板
这一步关系到最终产生的文档的使用舒适和方便度。大家直接自己创建一个飞书 sheet 表格，设计一个模板进行评估，后续程序开发以此模板为对标。
模板主要包括：对齐格式，子 sheet 内容，标题，单元格合并规则，填充信息等。
填充数据来源：可以是外部的任何数据，只要能拿到，该需求数据来自数据库。
4. API 调试，并借助 API 能力进行实际的后端开发。
飞书的开发文档给出了 api-http 的请求结构，可先行采用 http 走一遍全流程，但是并不需要自己去写详细的 http，开放平台提供了调试工具 Postman 的模板库（含有所有的环境变量配置以及请求结构），导入即可，不需自己一个个去写，改改参数就行。
大家在后端完整接入之前，可以采用 postman 串一遍流程。
在开发过程中，不能避免会和访问凭证打交道，而不同的请求类型具有不同的凭证需求（告知飞书服务器“谁在调这个接口”），大家一般采用 tenant_access_token 可满足要求。
5.进入后端开发
在调研清楚并能够采用 api 接口完成整个流程后，则开始 coding：
Tips: 以下给出的操作对飞书 api 的请求&回包过程进行了封装，在调研后可自行封装（仅做部分展示）
// CreateFeiShuOpenApp 创建app，进行配置，获取需要的关键结构（自封装）
func CreateFeiShuOpenApp(ctx context.Context, appId, appSecret string) (fsOpenApp *FsOpenApp) {
fsOpenApp = &FsOpenApp{}
//获取默认配置
appSettings := core.NewInternalAppSettings(core.SetAppCredentials(appId, appSecret)) // 必需
// 当前访问的是飞书，使用默认的内存存储（app/tenant access token）、默认日志（Error级别）
fsOpenApp.conf = core.NewConfig(core.DomainFeiShu, appSettings, core.SetLoggerLevel(core.LoggerLevelError))
//初始化需要用到的services
//bitableSvc--飞书sheet相关操作
fsOpenApp.getBitableSvc()
//authenSvc--文档权限相关操作
fsOpenApp.getAuthenSvc()
...
//服务端ctx
fsOpenApp.Ctx = ctx
//飞书后端ctx
fsOpenApp.coreCtx = core.WrapContext(ctx)
return fsOpenApp
}
// GetFolderInfo 获取根目录文件夹信息
// [in]: 1.parentFolderToken--父文件夹token 2.fileType--需要查询的文件类型 doc、sheet、file、folder
func (fsOpenApp *FsOpenApp) GetFolderInfo(parentFolderToken, fileType string) (parentToken string,
children map[string]*oapi_explorer.Child, svcErr *constant.ErrorException) {
//构建请求
folderSvc := fsOpenApp.getExplorerSvc().Folders
folderChildrenReq := folderSvc.Children(fsOpenApp.coreCtx)
folderChildrenReq.SetFolderToken(parentFolderToken)
folderChildrenReq.SetTypes(fileType)
//发起请求
if err != nil {
xxx
return , nil, svcErr
}
return folderChildrenResult.ParentToken, folderChildrenResult.Children, nil
}
...
五、更多相关开发心得
1.可能有开发者会问，调用飞书的API，为什么需要创建一个应用呢？
首先这是飞书的应用开发流程要求的。我个人理解，这主要还是和权限&安全相关，如果开放 API 给任何人用，任何人都可以操作其他人的数据，这不就乱套了嘛。创建一个应用，收敛权限为：只有管理员和协作者有操作权限，若不申请相关权限，是不能获取企业内他人信息的。
2.那么应用如何解决个人的权限隔离问题？
就调用 API 来自动创建文档需求而言，创建的文档在 应用本身自己的空间中（后续若让其他人有操作权限，需通过 api 添加权限或转移所有权）。或者讲：自己的空间自己操作。
3.如何理解开发者调用api的行为与应用之间的关系？
应用本身有自己的空间，一种好的类比理解是：新建应用（注册一个飞书账号）--通过 API 操作应用（在账号内部自己正常做自己的事情，区别只在于一个通过 api，一个自己去点界面而已）。则其产出的文档肯定在自己的空间中，就好比在飞书自己的空间中创建的文档，如果没有授权，其他人是没有访问权限的。
4.企业自建应用 和 商店应用 应该建哪一个？该需求创建 商店应用 可以不可以？
5.关于 token 刷新问题：
如果采用 Postman 进行调试，一个明显的感知是 token 会自动过期，需要一直刷新，在这一点上，后端 api 获取的操作对象会自动进行刷新，比较方便。
6.如果处理量比较大，后端延迟严重，可初步将数据填充完后及时将链接返回，其他的调整格式的耗时操作后续自动处理。
思路：创建在线文档--数据处理-填充数据--SendLark（发送链接到群）--格式调整--end 实现：打开链接--查看数据--格式自动在调整
关键点：在返回时做文档权限的转移（飞书平台 -> 操作者）
六、收益评估&写在最后
整体来看，本需求的成功实施，减少了无效人力的浪费（15min/人/次），因为属于长期收益，随着时间的推进，团队收益越大。
开发的工作量上，本次需求研发整体花费 4 天（包含调研 1 天➕设计方案 1 天➕开发调试 2 天），相对于需求收益来说，可基本持平。而且在调研阶段充分认识了飞书开放后台的此种能力以及其他包括（机器人等）的能力，在后续的工作中，该种能力得到复用，整体收益还是比较大的。
本需求其实属于一个比较小的优化点，其关键技术较少，但收益可量化、可评估。在平时的开发过程中，及时解决痛点很重要，小的痛点可随着时间放大为大的痛点。
飞书套件中提供的日历、通讯录、云文档、会议室、任务、考试等功能，其实基本都有相关 API 提供，大家可以探索研究下飞书开放能力，研发更多提升工作效率的玩法。
