Talk Services

简聊聚合服务代码与文档

文件目录

• images/ 所有图片文件保存地址，包括每个服务的图标和教程截图，图标以服务名@2x.png形式命名，教程以服务名-序号.png形式命名

• manuals/ 所有服务的文字教程地址，每个服务都配有中英文教程，以服务名-语言.md形式命名，使用 Markdown 格式编写。教程中引用的文件地址以绝对路径表示，如/images/inte-guide/jenkins-1.png

• src/ 源代码目录，每个服务的业务逻辑代码保存在 src/services/服务名.coffee 中

• test/ 测试代码目录，每个服务的测试代码保存在 test/services/服务名.coffee 中，另有一级子目录 test/services/服务名_assets 用于保存每个服务的模拟数据

开发教程

1. 每个服务都需要在代码中配置相关名称，模板，描述等，例如 incoming.coffee 文件中定义的 Incoming Webhook 服务

util = require '../util'

module.exports = ->

  # 服务标题，可使用中文名
  @title = 'Incoming Webhook'

  # 服务模板，大部分服务都以 webhook 形式接入简聊，可直接使用 webhook 模板
  @template = 'webhook'

  # 每个服务的简要描述，显示在聚合列表中，需中英文版本
  @summary = util.i18n
    zh: 'Incoming Webhook 是使用普通的 HTTP 请求与 JSON 数据从外部向简聊发送消息的简单方案。'
    en: 'Incoming Webhook makes use of normal HTTP requests with a JSON payload.'

  # 每个服务的详细描述，显示在配置页面中，需中英文版本
  @description = util.i18n
    zh: 'Incoming Webhook 是使用普通的 HTTP 请求与 JSON 数据从外部向简聊发送消息的简单方案。你可以将 Webook 地址复制到第三方服务，通过简单配置来自定义收取相应的推送消息。'
    en: 'Incoming Webhook makes use of normal HTTP requests with a JSON payload. Copy your webhook address to third-party services to configure push notifications.'

  # 服务图标，同为绝对路径表示
  @iconUrl = util.static 'images/icons/[email protected]'

  # 服务需增加的额外字段，如果使用 webhook 模板，需增加 webhookUrl 字段及对应的字段描述
  @_fields.push
    key: 'webhookUrl'
    type: 'text'
    readOnly: true
    description: util.i18n
      zh: '复制 web hook 地址到你的应用中来启用 Incoming Webhook。'
      en: 'To start using incoming webhook, copy this url to your application'

  # 监听服务事件，处理业务逻辑
  @registerEvent 'service.webhook', _receiveWebhook

2. 监听事件后，可编写相应的业务逻辑代码，例如监听 service.webhook 事件，当收到来自第三方服务的 webhook 请求时，会将请求体作为参数传入事件的处理方法中

_receiveWebhook = ({query, body}) ->
  # 读取请求中的 query, body 对象
  payload = _.assign {}
    , query or {}
    , body or {}

  {content, authorName, title, text, redirectUrl, imageUrl} = payload

  throw new Error("Title and text can not be empty") unless title?.length or text?.length or content?.length

  # 将请求组合成 message 对象
  message =
    body: content
    authorName: authorName
    displayType: payload.displayType

  # message 对象可以添加附件属性
  if title or text or redirectUrl or imageUrl
    message.attachments = [
      category: 'quote'
      data:
        title: title
        text: text
        redirectUrl: redirectUrl
        imageUrl: imageUrl
    ]

  # 在方法最后返回 message 对象，API 将此对象包装后推送给客户端
  # 如果方法中返回 null, false, undefined，API 将忽略这次请求而不推送任何消息
  message

3. 支持的事件列表

事件名	事件处理方法参数	需要的返回值	描述
integration.create	包含 integration 属性的 req 对象		创建聚合后触发
integration.update	包含 integration 属性的 req 对象		更新聚合后触发
integration.remove	包含 integration 属性的 req 对象		删除聚合后出发
service.webhook	req 对象	如返回 message 对象，则推送消息到客户端	当收到 webhook 请求时触发
before.integration.create	包含 integration 属性的 req 对象		创建聚合前触发
before.integration.update	包含 integration 属性的 req 对象		更新聚合前触发
before.integration.remove	包含 integration 属性的 req 对象		删除聚合前触发
message.create	包含 message 属性的 req 对象	如返回 message 对象，会发送一条回复消息给消息来源方	新消息时触发

代码测试

1. 每个服务需要有对应的测试代码，大部分代码可用模拟数据测试，如测试 incoming webhook

should = require 'should'
Promise = require 'bluebird'

loader = require '../../src/loader'  # 加载 loader
{req} = require '../util'            # 从 util 中取得模拟的 req 对象
$incoming = loader.load 'incoming'   # 从 loader 加载对应服务

describe 'Incoming#Webhook', ->

  it 'receive webhook', (done) ->
    # 模拟 webhook 请求结构体
    req.body =
      authorName: '路人甲'
      title: '你好'
      text: '天气不错'
      redirectUrl: 'https://jianliao.com/site'
      imageUrl: 'https://dn-talk.oss.aliyuncs.com/site/images/workspace-84060cfd.jpg'

    $incoming.then (incoming) ->

      # 触发 service.webhook 事件
      incoming.receiveEvent 'service.webhook', req

    .then (message) ->

      # 检测返回结果是否正确
      message.should.have.properties 'authorName'
      message.attachments[0].data.should.have.properties 'title', 'text', 'redirectUrl', 'imageUrl'

    .nodeify done