“这审批流到底什么时候能上线?业务那边已经催了三次了。”这是我两周前在项目群里看到的消息。一个运行了快十年的.NET Framework老系统,要加一套完整的审批流程,业务方点名要求“手机上能批、能看进度、最好跟飞书消息打通”。说实话,第一反应是头疼——老系统改工作流引擎,牵扯到数据库表、状态机、权限体系,没两三个月下不来。但后来我们换了个思路:不自己造审批流,直接把飞书审批流接进来,系统只负责发起审批和接收结果。整个集成从动手到上线,两个星期。这篇文章就把这次集成的完整思路、关键代码和踩过的坑整理出来,给同样被老系统审批需求困扰的朋友一个参考。
1. 为什么传统.NET系统要接飞书审批流
1.1 自建审批流的老路有多疼
我见过太多团队在自建审批流上栽跟头。业务刚开始提需求时,听起来很简单:提交一个申请,主管审批,完了归档。但一旦开始设计数据库,问题就来了——审批节点怎么存?审批人怎么配?会签还是或签?驳回之后是回到上一级还是退回发起人?加签、转交、催办、超时自动处理怎么办?这些还只是引擎层面的。等系统上线,移动端适配又成了新问题,总不能要求审批人天天开着电脑点审批。
当时我们盘了一下,这套自建方案如果做完整,光后端服务加前端页面,保守估计三个人干两个月。而且老系统的技术栈是.NET Framework 4.7.2 + Web Forms,团队里已经没人愿意在这个基础上继续堆业务代码。业务部门的需求其实很朴素——能有个地方审批,审批人能收到通知,能在手机上处理。他们要的从来不是审批流引擎,而是审批这件事能被高效完成。
1.2 飞书审批流能提供什么
飞书审批这个模块,底层是一个完整的工作流引擎,节点类型、审批人规则、消息通知、移动端、PC端、操作记录、导出报表,这些都是现成的。作为开发者,我们不需要去理解引擎内部的实现,只需要通过API做三件事:发起审批实例、查询审批结果、接收审批状态回调。
这种集成方式的好处是显而易见的。第一,开发量大幅减少,核心代码量也就几百行。第二,审批体验是业界标准,员工用飞书就能处理审批,不需要重新学习一套后台系统。第三,后续维护成本低,飞书侧的更新迭代由官方负责,我们只需要保证接口稳定。第四,消息通知天然打通,审批人收到卡片消息,点击直接跳转审批详情,这个体验自建系统很难做好。
更重要的是,飞书审批流是“外部系统可嵌入”的。通过开放平台的API,可以把审批实例嵌入到任何系统的业务流程中——老系统里点提交,飞书里走审批,审批结果再通过回调推回老系统。整个过程对老系统来说是异步解耦的,不会因为审批引擎的负载影响主业务。
1.3 什么样的场景适合这种方案
并不是所有审批需求都适合接飞书。我个人的判断标准很简单:如果审批流程主要用于内部管理、审批人都是企业内部员工、审批过程需要良好的移动端体验,那接飞书就是性价比最高的方案。比如费用报销审批、采购申请、请假加班、合同会签、用章申请这类场景,流程本身不复杂,但对通知能力和移动端体验要求高,非常适合。
反过来,如果审批是核心业务的一部分,需要跟业务数据深度绑定,比如订单审批通过后要自动触发下游系统、需要灵活的审批路由策略、审批过程中要动态展示业务数据,那可能还是要做自建引擎。但在实际项目中,80%的审批需求都没到这个复杂度,用飞书完全够用。我们这次做的就是一个设备领用审批,需要关联设备编号、使用人、存放地点这些字段,流程只有两级审批,飞书审批流完全能覆盖。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 集成前的准备:应用创建与权限配置
2.1 创建企业自建应用
去飞书开放平台(open.feishu.cn),用管理员账号登录,进入“开发者后台”,点击“创建应用”,选择“企业自建应用”。这里需要填应用名称和描述,名称建议用业务相关的名字,比如“设备管理系统-审批助手”,这样在审批列表里用户能一眼认出来这个审批来自哪个系统。
创建完成后,进入应用详情页,有几个关键信息需要先记下来:App ID、App Secret。这两个参数相当于应用在飞书开放平台上的账号和密码,后续调用所有API都需要用到。注意App Secret一定不能泄露到前端代码或者公共代码仓库里,我们团队甚至会在代码评审时专门检查这个。
还有一个细节,如果企业用的是飞书专业版或旗舰版,开放平台的接口权限会更全,审批接口属于“审批”应用能力。如果你发现某个接口返回“权限不足”,多半不是代码问题,而是应用没开通对应权限,或者企业版本不支持。
2.2 权限点申请与发布
在应用详情页左侧菜单里找到“权限管理”,搜索审批相关的权限点。我们需要重点关注这几个权限:
- approval:approval(查询审批定义)
- approval:approval_instance(创建和查询审批实例)
- contact:user.base:readonly(读取用户基本信息,用于匹配审批人)
点击“开通”后,权限状态会变成“申请中”。这里有个容易踩的坑:自建应用的权限申请需要企业管理员审核。如果是在开发环境调试,建议直接用管理员账号创建应用并自行审核通过;如果是在客户现场,需要提前跟客户的管理员打好招呼,避免权限卡住导致项目延期。
权限通过后,还需要“创建版本并发布”。这一步是很多新手容易忽略的——权限开了,但应用还没发布,调用API时依然会提示“应用未发布”。发布流程是:在“版本管理与发布”页面创建版本,填写版本号、更新说明,然后提交发布。企业自建应用发布后,企业内所有用户就都能看到这个应用了,包括审批流里会用到的审批人。
2.3 事件订阅与回调地址配置
审批结果不能全靠轮询,飞书支持通过事件订阅主动推送审批状态变化。在应用的“事件与回调”页面,添加“审批实例状态变更”事件(approval_instance_status_change)。配置这个事件有两个关键参数:请求地址(Request URL)和Encrypt Key。
请求地址必须是一个公网可访问的HTTPS地址,飞书服务器会向这个地址发送事件通知。Encrypt Key用于事件内容的加密解密,飞书推送的事件内容默认是加密的,需要在服务端解密后才能读取明文。
这里提醒一下,开发调试阶段如果没有公网地址,可以用内网穿透工具把本地服务暴露到公网,但要注意安全。正式环境建议部署在公司的API网关后面,确保飞书的请求能被正确路由到.NET服务。请求地址的校验机制是飞书先发送一个验证请求,服务端需要按指定规则返回加密后的challenge,校验通过后订阅才算生效。这个校验逻辑后面会详细说。
3. .NET侧的核心对接细节
3.1 获取tenant_access_token
飞书开放平台API的鉴权方式是Bearer Token,需要先调用接口获取tenant_access_token。这个Token的有效期是2小时,过期后需
