飞书的开发者后台——开放平台入口

为什么飞书的开放平台值得你单独去了解

我第一次真正认真看飞书开放平台，是因为公司在接一个第三方CRM系统时候卡了壳。那会儿团队里有人提议直接让开发去飞书后台捞接口，结果在开放平台里转了半天，连个像样的API文档入口都没找到。后来才弄明白，飞书的开放平台其实是个独立站点，叫开放平台，和普通的飞书管理后台不是一个地方。很多人刚接触时候都容易搞混——你在飞书电脑端或者网页管理后台能看到的是日常的权限、审批、考勤设置，但想自己做应用、接第三方、搞自动化流程，就得走开放平台那条路。

开放平台说白了就是飞书给开发者、企业IT、甚至普通超级管理员准备的“后台中的后台”。我见过不少公司的运营同学以为在管理后台里点几下就能接上某个工具，结果发现连应用创建按钮都找不到，最后只能找技术同事帮忙。实际上，从飞书个人版升级到企业版，或者从普通账号切换到管理员账号后，你才能看到开放平台的真正入口。但更直接的办法是，直接在浏览器搜“飞书开放平台”，点进去后就是那个熟悉的蓝白界面。

下载与安装开放平台需要的东西

飞书开放平台本身不是你需要下载的软件，它是个网页端平台。但你想用它做一些事情，比如开发机器人、写自定义审批流，或者挂接外部系统，那你的电脑上确实需要装飞书客户端。这个客户端从飞书官网下载就行，点本页下载按钮，选对应系统的版本。我自己的习惯是，不管换几台电脑，都直接用官网那个下载入口，因为有时候第三方下载站给的包版本会落后一两个小版本，新功能用不了还挺烦的。

安装过程其实没什么特别的，打开安装包按下一步就行。不过有个坑我踩过几次：如果你是在公司内网环境下装，尤其是网络管控严格的那种，飞书客户端联网激活可能会卡住。有次我在客户那边帮他们调开放平台的接口，装完飞书后死活登不上，后来发现是他们的防火墙把飞书的某些IP段给封了。解决办法是把相关的域名加到白名单，具体哪些域名，飞书官方帮助文档里其实写了，但很多人懒得翻。另一个常见问题是Mac电脑装完打不开，这是因为系统安全设置默认拦了非App Store下载的应用。去系统偏好设置->安全性与隐私里点“仍要打开”就行，不用去终端输什么神秘命令。

从开放平台入口找到应用创建和管理模块

登录开放平台后，第一眼看到的页面其实挺清爽的，左边是菜单，右边是内容区。但对于新手来说，这个界面还是有点懵，因为菜单里面东西多，比如有“应用”、“机器人”、“网页应用”、“小程序”这些分类。我第一次进去的时候，想创建一个简单的审批机器人，结果点到了“小程序”那一栏，后来才发现应该去“应用”下面创建。

具体操作步骤是：登录开放平台，默认会跳到应用列表页。如果你是企业管理员，这里会显示你们企业已有的应用。想创建新的，点左上角的“创建应用”按钮。弹出来的对话框会让你填应用名称和描述，还有个关键选项——应用类型。这里分好几种：自建应用、商店应用、ISV应用等。普通企业最常用的是自建应用，因为它不需要审核，直接就能在你自己的企业里用。我试过一次商店应用那个选项，结果提交后等了两天才通过，后来发现其实用不着，除非你想把你的应用发布到飞书应用商店让所有企业都能搜到。

创建好后，你会进到这个应用的详情页。这里有点像你给这个应用开的“个人档案”，左边菜单有“基础信息”、“权限管理”、“安全设置”、“事件订阅”等。一开始可能觉得乱七八糟，但其实常用的就是那么几块：开发配置主要在“权限管理”和“事件订阅”里，测试的话去“版本管理与发布”那边弄个测试版。我有个小建议，刚创建应用不要急着配一堆权限，先把应用名写好，描述写清楚，然后去“安全设置”里把App ID和App Secret记下来。这两个东西后面开发的时候要用，丢了很麻烦，自己后台还只能重置不能直接找回。

配置应用权限和事件订阅时的真实操作

权限管理这块，我花了不少时间才搞明白。飞书开放平台的权限系统分得非常细，比如“获取用户信息”是一个权限，“发送消息”是另一个权限，“读取审批实例”又是一个权限。你想要自己的应用能做什么，得先在这里申请对应的权限。这个设计本意是好，比某些平台一口气给你所有权限安全得多，但实际操作起来有点烦。有次我给一个机器人应用加“发送消息”权限，申请之后还得等管理员审核，而我自己就是管理员，还得自己点个批准，有点奇怪但确实就是这么设计的。

申请权限的时候有个小技巧：如果不是特别清楚需要哪些权限，可以先看飞书官方提供的API文档。每个API接口页面下面都会列出一段代码片段，其中有个字段叫“permission”，那里面就写了调用这个API需要哪些权限。我抄过几次，发现确实准。比如你想让你的机器人能向群聊发消息，API文档里会写“im:message:send_as_bot”这个权限。然后你回到权限管理页面，搜这个权限名就能找到，勾上就行。

事件订阅这块更考验耐心。简单说，事件订阅就是让飞书在发生某些事的时候主动通知你的应用。比如用户向机器人发了一条消息，或者审批流程通过了一个步骤，你可以在这里配置一个回调地址，让飞书把事件推送到你自己的服务器。这个回调地址必须是公网能访问的HTTPS地址，而且得符合飞书要求的格式。我当初为了调试这个，用了一个内网穿透工具，把本地开发环境的端口暴露到公网，然后在事件订阅里填上那个地址。那一整个下午都在看回调日志，因为总是报签名校验失败，后来发现是验证Token和Encrypt Key没填对——这两个在事件订阅页面最上面有显示，复制下来然后粘贴到服务端的配置里就行。

开发和测试机器人应用时遇到的那些坑

真正开始写代码的时候，很多人会首选飞书提供的开放平台SDK。飞书官方支持Python、Java、Go、Node.js这几种语言的SDK。我用过Python和Java两套SDK，感觉Python那套文档更清晰一些，Java的文档有些地方简略，得自己翻GitHub上的源码。但不管用哪种，安装SDK基本就是一个命令的事，比如Python的用pip install lark-oapi就行。不过要注意，SDK的名字和版本号有时候会变，我遇到过lark-oapi这个包被下架重新上新的情况，所以最好去飞书开放平台的SDK页面，点本页下载按钮先把最新的whl文件或jar包下载下来，保险一点。

开发过程中我吃过最大的一个亏，是在配置消息卡片的时候。飞书的机器人可以发带按钮、下拉菜单的交互式消息卡片，这点比其他IM工具强大很多。但卡片的配置是用JSON写的，而且JSON结构特别复杂。有次我想在卡片里加一个带确认弹窗的按钮，我在卡片的JSON里写了action字段，结果怎么都触发不了回调。后来去看文档，发现卡片的交互事件需要额外在“事件订阅”里订阅“message_card_action”事件，而且回调地址里还要做特殊处理。折腾了整整一个下午，最后发现其实官方有在线卡片格式校验工具，在开放平台左侧菜单的“工具”里，可以粘贴JSON去验证格式对不对。

测试应用的时候，飞书开放平台提供了沙箱环境和测试企业。我在测试企业里加过几个假用户，用来验证机器人发消息和接收消息的逻辑。测试企业可以直接在应用详情页的“测试设置”里创建，不用填真实的企业信息。但有个限制：测试企业最多只能加200个人，虽然一般够用了，但万一你的应用需要大量并发测试，可能还得上更复杂的方案。另外，测试企业内的数据不会影响到真实企业，这点很放心。

发布和上线飞书应用的完整流程

当你把所有开发工作做完，机器人也测试通过后，下一步就是发布。发布这块的操作路径在应用详情页的“版本管理与发布”里。点进去后能看到一个“创建版本”的按钮。它要求你填版本号、更新说明，还得上传应用的图标。图标有尺寸要求，我记得是192x192像素，格式是PNG。我一直用一张简单蓝色底加白色“F”字的图标，省得每次改。

版本提交后，如果是自建应用，直接点“申请发布”就行，然后去管理后台的“应用审核”里点一下批准，这个版本就上线了。自建应用的好处就是快，前后可能几分钟就搞定了。但如果你想上架到飞书应用商店，让其他企业也能使用，那就得走ISV应用的发布流程。那个流程需要飞书官方审核，我第一次提交的时候因为应用描述里写了“超级好用”这种字眼，被打了回来，要求改成更客观的描述。后来老老实实写了功能和适用场景，就通过了。整个审核周期大概两到三天，周末不算。有次我周四下午提交了一个更新，一直到下周一晚上才通过，所以在内部项目里尽量别卡在周五发版。

还有一点要注意的是，应用上线后，如果你要改权限或事件订阅，得重新发布一个新版本。这个设计一开始觉得麻烦，后来想想其实挺合理，避免了一边有人用旧版本一边有新权限在跑造成冲突。我吃过一次亏——更新了权限后没发新版本，结果测试环境能用，生产环境还是老样子。解决办法就是每次改完配置，一定记得去“版本管理与发布”里创建新版本并发布。

日常维护和监控应用的小技巧

应用上线后不是万事大吉，开放平台里有些工具能帮你追踪应用是不是在正常运行。比较重要的是“应用监控”那块，在应用详情页的左侧菜单能找到。这里面有调用次数、成功率、错误码分布这些指标。我习惯每周一看一次，如果有突然的失败率飙升，大多是回调地址出了问题。比如你的服务器SSL证书过期了，或者被攻击导致服务宕机，飞书那边调用你的回调接口时就会报网络错误。

还有一个我特别喜欢的功能是“日志管理”。那里记录了飞书调用你应用接口的每一次请求，包括请求时间、IP、返回码、具体错误信息。有次用户反馈机器人没有回复消息，我去日志里查，发现是用户输入的参数格式不对，我写的代码里没有做兼容处理。这个日志默认保存3天，如果3天内的日志还能查到，建议把关键日志下载下来，因为过几天就清空了。下载入口就在日志页面的右上角，点那个导出按钮就行。

另外，万一你的应用出了大问题，比如发错了消息，开放平台有个“关闭应用”的紧急操作。在应用详情页的最下方，“更多操作”里有个“停用应用”，点一下所有用户就收不到这个应用的消息了。我虽然只用过一次，但那次确实帮了大忙——测试的时候忘记切换环境，在真实企业里发了一堆测试消息，赶紧停用应用才没造成更大的混乱。但注意停用后重新启用，得去管理后台操作，但那些已经发出去的消息是收不回来的，所以调试时候千万别在真实群里测试。