先定好输入格式再谈实时——Vivix 接入前最容易搞反的顺序

接入 Vivix 这类带实时能力的服务时，常见的做法是先跑一个最小请求把延迟看清楚，再回头整理业务输入格式。这个顺序通常会在第二周出问题：一旦输入从纯短句扩到中英混排、带数字单位或超长文本，返回结构跟着变，前端消费逻辑要重写，联调轮次被一轮轮推高。更稳的顺序是把业务侧真实会出现的输入格式先钉死并逐种验证返回结构，确认前端能直接消费之后，再在同一批固定输入上压实时表现。这样实时性数据才有对照基准，格式变更也不会把已有结论作废。

适用场景：准备接入或刚接入 Vivix、业务输入并非单一短文本的项目。操作动作：先列输入组合清单并约定字段与长度，用最小请求逐种确认返回结构，再在调用前加一层格式校验，最后在同一输入集上记录耗时波动。验证方式：看返回字段能否被现有前端直接渲染、看拦截日志是否挡住非法组合、看重复调用的耗时区间是否收敛。风险边界：格式范围只能覆盖业务可枚举的场景，超出清单的输入应先拦截而不是放行试跑；实时性结论只在格式固定后的同一输入集上成立，格式一变需重新记录。

列出业务侧真实会出现的输入组合

这一步的目的不是穷举所有字符串，而是把格式范围限定在实际会出现在页面上的输入。做法是翻最近一段时间的真实业务日志（表单提交、评论、搜索词、客服会话均可），按形态归类，而不是凭想象列。归类后与产品确认哪几类必须支持，其余明确为不支持并在调用前拦掉。

一份可用的组合清单通常包含以下几类，具体以你的业务为准：

短文本：纯中文或纯英文，单句，不含特殊符号
长文本：多句、带标点、可能含换行
中英混排：含英文缩写、产品型号、括号注释
数字与单位：金额、时长、百分比、计量单位
含表情或特殊符号：用户 UGC 场景常见
边界输入：空串、纯空白、超出长度上限、只有符号

每一类都要落成字段约定，下面是示例结构，字段名和上限需要结合 Vivix 侧的输入限制与环境确认后填写：

组合名        必填字段            长度约定            是否必须支持
short_zh    text               1-50 字符           是
long_mix    text, locale       51-500 字符         是
num_unit    text, unit_hint    1-80 字符           是
emoji_text  text               1-100 字符          视业务确认
edge_empty  text               0 字符              否（前置拦截）
edge_long   text               >500 字符           否（前置拦截）

约定里有两件事必须写清楚：一是长度按字符还是按字节计，中英混排时两者差别明显；二是 locale 这类辅助字段是业务侧自己拼进请求，还是由服务端推断。这两点不写清，后面每次联调都会重新讨论一遍。

用最小请求逐种验证返回结构

格式清单确定后，不要等前端页面做好再联调。先用最小请求把每种组合各打一次，把返回的字段名、类型、层级记下来，重点看两件事：返回字段是否稳定、这些字段能否被现有前端直接消费。下面是通用请求骨架，URL、鉴权头和参数名按 Vivix 实际控制台给出的信息替换：

curl -X POST 'https://<vivix-endpoint>/<your-path>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "<按组合清单替换>",
    "locale": "zh-CN"
  }'

每种组合跑完后，把结果记成一张对照表，比只看单次返回有用得多：

组合名        返回字段            类型        前端可否直接消费    备注
short_zh    text, result        string      是                  -
long_mix    text, result, meta  object      否，meta 需拍平     标注不一致
num_unit    text, result        string      是                  -
emoji_text  报错或降级          -           待确认             标注不一致

“不一致之处”要单独标注，不要混在正常项里。常见的三类不一致：同一组合两次返回字段数不同；某类输入触发了降级但返回结构未提示；返回里出现业务侧没有约定的附加字段。这三类都会让前端写条件分支，越晚发现返工越多。判断标准是：能否用同一段渲染逻辑覆盖清单内所有组合，不能覆盖的把差异点写进对接说明。

在调用前加一层格式校验拦截不支持的组合

校验层的职责是把明显不支持的输入挡在业务侧，减少无效调用和后续排查成本。它不负责保证语义正确，只负责保证“送进 Vivix 的输入落在已验证过的组合范围内”。位置建议放在业务代码调用封装函数之前，或网关的业务前置钩子里。

下面是一段可替换的校验样例，规则表来自上一节的组合清单，长度上限与字符集需按实际约定修改：

INPUT_RULES = [
    {"name": "short_zh",   "min": 1, "max": 50,  "required": True},
    {"name": "long_mix",   "min": 51, "max": 500, "required": True},
    {"name": "num_unit",   "min": 1, "max": 80,  "required": True},
]

def validate_input(text: str, locale: str = "zh-CN"):
    if text is None or not text.strip():
        return False, "empty_input"
    if len(text) > 500:
        return False, "too_long"
    if not any(r["min"] <= len(text) <= r["max"] for r in INPUT_RULES):
        return False, "out_of_range"
    if locale not in ("zh-CN", "en-US"):
        return False, "unsupported_locale"
    return True, "ok"

拦截后返回给前端的文案要能指导用户改，而不是只说失败。可直接参考下面几组，按产品语气微调：

empty_input：请先输入内容再提交
too_long：内容超出可处理长度，请精简后再试
out_of_range：当前内容格式暂不支持，请调整后重试
unsupported_locale：当前语言暂不支持，请切换后重试

上线后需要验证拦截是否真的生效：在测试环境分别提交空串、超长文本、非约定语言，确认请求没有打到 Vivix 侧，只在业务日志里留下拦截记录。如果日志里能看到请求已发出但被下游拒绝，说明校验层位置放错了。

格式稳定后再压实时表现并记录波动

只有在组合清单、返回结构和校验规则都不再改动之后，实时性数据才有意义。这时用同一批输入重复调用，记录每次耗时，而不是只看一次结果。建议对每种组合各跑固定的若干次，记录最小值、最大值和中间水平，观察波动范围。

组合名        调用次数    最小耗时    最大耗时    中间水平    备注
short_zh        <填>       <填>       <填>       <填>      是否与时段有关
long_mix        <填>       <填>       <填>       <填>      -
num_unit        <填>       <填>       <填>       <填>      -

判定结论按这个口径写：如果在同一输入集、同一网络环境下，最大与最小耗时差距收敛且没有持续抬升趋势，可以先认为当前格式下的实时性达到可用水平；如果波动明显，先排查网络、并发和超时重试设置，不要回头修改输入格式来“改善速度”，那会让已有对照数据全部失效。另外，长文本组合的耗时通常高于短文本，比较时应按组合分别看，不要混成一个平均数字。

每次格式变更后，这张表需要重跑一遍并在备注里注明变更点，否则下次排查延迟问题时无法判断是格式引起还是环境引起。记录文件建议与输入组合清单放在同一处，交给后续接手的人时能直接对上。