@milian/linker-cli 0.0.0-stage → 0.17.3

package/src/commands/api-create.js

@@ -0,0 +1,478 @@
+'use strict';
+
+const fs = require('fs');
+
+const { loadCredentials } = require('../config');
+const { authedRequest } = require('../api');
+const { resolvePlatformRecord } = require('./platforms');
+const { publishWithRetry, DEFAULT_MAX_RETRY } = require('./api-publish');
+const {
+  buildParamTree,
+  buildResultTree,
+  buildSaveBody,
+  normalizeUrl,
+  normalizeLabels,
+  parseQueryKeys,
+  parseHeaderKeys,
+  parseContentType,
+  prettyExample,
+  pickOutboundApiId,
+  renderTree,
+  MAX_LABEL_LENGTH
+} = require('../schema');
+
+const METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+
+const USAGE = `用法: wb api create --platform <platformId|名称> --name <api名称> --url </path> [选项]
+
+必填:
+  --platform, -p <id|名称>   目标连接器应用
+  --name, -n <名称>          API 资源名称
+  --url, -u <path>           api 路径，必须以 / 开头，不带 host
+                            路径参数写成 /a/{orderId}/b，会自动转成 /a/orderId/b 并把 orderId 放进 query 参数
+
+可选:
+  --method, -m <方法>        GET|POST|PUT|DELETE|PATCH，默认 POST
+  --body <json|@file>        请求体示例，用于自动生成 requestBody 结构树
+  --result <json|@file>      响应体示例，用于自动生成 responseBody 结构树
+  --query, -q "a=1&b=2"      query 参数（只取参数名）
+  --header, -H "e: 2"        请求头（可重复；Content-Type 会被忽略，由 --content-type 表达）
+  --content-type <0-6>       0=none 1=json 2=soap+xml 3=xml 4=form 5=multipart 6=octet-stream
+                            默认 GET 为 0，其余为 1
+  --required <a,b.d>         必填字段路径（body 用点号分隔，如 b.d）
+  --label "<路径>=<注释>"     字段描述，来自接口文档注释。可重复
+                            可加作用域前缀：req:/res:/param:/header:，如 "res:data.id=主键"
+                            不加前缀则同时作用于入参和出参
+  --labels <json|@file>      一次性给全部字段注释，结构：
+                            {"request":{"b.d":"订单号"},"response":{"data.id":"主键"},
+                             "param":{"pageNo":"页码"},"header":{"x-tenant":"租户"}}
+                            也可给扁平 {"b.d":"订单号"}（同时作用于入参和出参）
+                            单条注释不得超过 ${MAX_LABEL_LENGTH} 字符，超了请先自行总结
+  --remark, -r <描述>        api 描述，默认与名称相同
+  --host-id <platformHostId> 手工指定 platformHostId（默认取连接器 hostBOList[0]）
+  --update <outboundApiId>   更新已有 API 资源而不是新建
+  --no-publish               只保存，不走发布
+  --max-retry <N>            发布路径冲突时自动改路径重试次数，默认 ${DEFAULT_MAX_RETRY}
+  --url-suffix <word>        路径冲突时使用的后缀单词（默认按 api 名称推导）
+  --dry-run                  只打印将提交的 JSON，不发请求
+  --json                     输出接口原始 JSON
+
+示例:
+  wb api create --platform 泛微E10 --name 查询订单 --url /order/query \\
+      --method POST --body @body.json --result @result.json --labels @labels.json
+
+  wb api create --platform 泛微E10 --name getUser --url "/user/{userId}" \\
+      --method GET --query "withDetail=1" --dry-run`;
+
+function parseArgs(argv) {
+  const opts = {
+    platform: '',
+    name: '',
+    url: '',
+    method: 'POST',
+    body: '',
+    result: '',
+    query: '',
+    headers: [],
+    contentType: '',
+    required: '',
+    labels: '',
+    labelList: [],
+    labelSpecs: [],
+    remark: '',
+    hostId: '',
+    update: '',
+    publish: true,
+    maxRetry: DEFAULT_MAX_RETRY,
+    urlSuffix: '',
+    dryRun: false,
+    json: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[i + 1];
+      i += 1;
+      return v === undefined ? '' : v;
+    };
+    if (a === '--platform' || a === '-p') opts.platform = next();
+    else if (a === '--name' || a === '-n') opts.name = next();
+    else if (a === '--url' || a === '-u') opts.url = next();
+    else if (a === '--method' || a === '-m') opts.method = next();
+    else if (a === '--body') opts.body = next();
+    else if (a === '--result') opts.result = next();
+    else if (a === '--query' || a === '-q') opts.query = next();
+    else if (a === '--header' || a === '-H') opts.headers.push(next());
+    else if (a === '--content-type') opts.contentType = next();
+    else if (a === '--required') opts.required = next();
+    else if (a === '--label') opts.labelSpecs.push(next());
+    else if (a === '--labels') opts.labels = next();
+    else if (a === '--remark' || a === '-r') opts.remark = next();
+    else if (a === '--host-id') opts.hostId = next();
+    else if (a === '--update') opts.update = next();
+    else if (a === '--no-publish') opts.publish = false;
+    else if (a === '--max-retry') {
+      const v = Number(next());
+      opts.maxRetry = Number.isFinite(v) && v > 0 ? Math.min(Math.floor(v), 10) : DEFAULT_MAX_RETRY;
+    } else if (a === '--url-suffix') opts.urlSuffix = next();
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (!a.startsWith('-')) {
+      if (!opts.platform) opts.platform = a;
+      else if (!opts.name) opts.name = a;
+      else if (!opts.url) opts.url = a;
+    }
+  }
+  return opts;
+}
+
+/**
+ * 读取"JSON 或文件"入参：支持 @file 前缀、裸文件路径、内联 JSON。
+ * @returns {{value:any, source:string}|null}
+ */
+function readJsonSource(raw, label) {
+  const v = String(raw == null ? '' : raw).trim();
+  if (!v) return null;
+
+  let filePath = '';
+  if (v.startsWith('@')) filePath = v.slice(1).trim();
+  else if (fs.existsSync(v) && fs.statSync(v).isFile()) filePath = v;
+
+  if (filePath) {
+    if (!fs.existsSync(filePath)) throw new Error(`${label} 文件不存在：${filePath}`);
+    const text = fs.readFileSync(filePath, 'utf8');
+    try {
+      return { value: JSON.parse(text), source: filePath };
+    } catch (err) {
+      throw new Error(`${label} 文件不是合法 JSON（${filePath}）：${err.message}`);
+    }
+  }
+
+  try {
+    return { value: JSON.parse(v), source: 'inline' };
+  } catch (err) {
+    throw new Error(
+      `${label} 既不是合法 JSON 也不是可读文件：${err.message}\n` +
+        `        内联示例请用单引号包裹：--body '{"a":1}'；文件请写 --body @body.json`
+    );
+  }
+}
+
+function normalizeMethod(raw) {
+  const m = String(raw == null ? '' : raw).trim().toUpperCase();
+  if (!m) return 'POST';
+  if (!METHODS.includes(m)) {
+    throw new Error(`--method "${raw}" 不合法：可选 ${METHODS.join(' / ')}`);
+  }
+  return m;
+}
+
+/** --label 的作用域前缀别名 */
+const LABEL_SCOPE_ALIASES = {
+  req: 'request',
+  request: 'request',
+  body: 'request',
+  res: 'response',
+  response: 'response',
+  result: 'response',
+  param: 'param',
+  query: 'param',
+  path: 'param',
+  header: 'header'
+};
+
+const ALL_SCOPES = ['request', 'response', 'param', 'header'];
+
+/**
+ * 汇总字段注释（labelName）来源，合成一个分域对象交给 schema.normalizeLabels。
+ *
+ * 优先级：--label 覆盖 --labels（更精确的写在后面）。
+ * 注释本该来自接口文档，CLI 不做任何推导，没给就留空。
+ */
+function buildLabelInput(opts) {
+  const merged = { request: {}, response: {}, param: {}, header: {} };
+
+  const push = (scope, key, text) => {
+    const k = String(key == null ? '' : key).trim();
+    if (!k) return;
+    merged[scope][k] = String(text == null ? '' : text);
+  };
+
+  // 1) --labels <json|@file>
+  const src = readJsonSource(opts.labels, '--labels 字段注释');
+  if (src) {
+    const v = src.value;
+    if (!v || typeof v !== 'object' || Array.isArray(v)) {
+      throw new Error(
+        '--labels 需要一个 JSON 对象，形如 {"request":{"b.d":"订单号"},"response":{"data.id":"主键"}}，' +
+          '或扁平形式 {"b.d":"订单号"}'
+      );
+    }
+    const keys = Object.keys(v);
+    if (keys.some((k) => ALL_SCOPES.includes(k))) {
+      for (const scope of ALL_SCOPES) {
+        const part = v[scope];
+        if (!part || typeof part !== 'object' || Array.isArray(part)) continue;
+        for (const [k, t] of Object.entries(part)) push(scope, k, t);
+      }
+    } else {
+      for (const [k, t] of Object.entries(v)) {
+        for (const scope of ALL_SCOPES) push(scope, k, t);
+      }
+    }
+  }
+
+  // 2) --label "path=注释" / "res:path=注释"
+  for (const spec of opts.labelSpecs || []) {
+    const raw = String(spec == null ? '' : spec);
+    const eq = raw.indexOf('=');
+    if (eq <= 0) {
+      throw new Error(`--label "${raw}" 格式不对：应为 "<字段路径>=<注释>"，如 "b.d=订单号"`);
+    }
+    let left = raw.slice(0, eq).trim();
+    const text = raw.slice(eq + 1).trim();
+
+    let scope = null;
+    const colon = left.indexOf(':');
+    if (colon > 0) {
+      const prefix = left.slice(0, colon).trim().toLowerCase();
+      if (LABEL_SCOPE_ALIASES[prefix]) {
+        scope = LABEL_SCOPE_ALIASES[prefix];
+        left = left.slice(colon + 1).trim();
+      }
+    }
+
+    if (scope) push(scope, left, text);
+    else for (const s of ALL_SCOPES) push(s, left, text);
+  }
+
+  return merged;
+}
+
+/** 收集并校验入参 */
+function collect(opts) {
+  const missing = [];
+  if (!String(opts.platform).trim()) missing.push('--platform  目标连接器（id 或名称）');
+  if (!String(opts.name).trim()) missing.push('--name      API 资源名称');
+  if (!String(opts.url).trim()) missing.push('--url       api 路径，必须以 / 开头');
+  if (missing.length) {
+    throw new Error(`缺少必填入参：\n        ${missing.join('\n        ')}\n\n${USAGE}`);
+  }
+
+  const apiName = String(opts.name).trim();
+  const method = normalizeMethod(opts.method);
+  const urlInfo = normalizeUrl(opts.url);
+
+  const bodySrc = readJsonSource(opts.body, '--body 请求体示例');
+  const resultSrc = readJsonSource(opts.result, '--result 响应体示例');
+
+  // 字段注释只来自 --label / --labels（接口文档），CLI 不做任何推导
+  const labelInfo = normalizeLabels(buildLabelInput(opts));
+
+  return {
+    apiName,
+    method,
+    url: urlInfo.url,
+    pathParams: urlInfo.pathParams,
+    bodyJson: bodySrc ? bodySrc.value : null,
+    bodySource: bodySrc ? bodySrc.source : '',
+    resultJson: resultSrc ? resultSrc.value : null,
+    resultSource: resultSrc ? resultSrc.source : '',
+    queryParams: parseQueryKeys(opts.query),
+    headerParams: parseHeaderKeys(opts.headers),
+    contentType: parseContentType(opts.contentType, method),
+    required: String(opts.required || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+    labels: labelInfo.labels,
+    labelClipped: labelInfo.clipped,
+    remark: String(opts.remark || '').trim() || apiName,
+    updateId: String(opts.update || '').trim()
+  };
+}
+
+/** 组装保存请求体（纯函数部分都在 schema 里） */
+function assemble(v, platform) {
+  const paramList = buildParamTree({
+    queryParams: v.queryParams,
+    pathParams: v.pathParams,
+    headerParams: v.headerParams,
+    bodyJson: v.bodyJson,
+    required: v.required,
+    labels: v.labels
+  });
+  const resultList = buildResultTree(v.resultJson, { labels: v.labels, required: v.required });
+
+  return buildSaveBody({
+    platformId: platform.platformId,
+    platformHostId: platform.platformHostId,
+    outboundApiId: v.updateId,
+    apiName: v.apiName,
+    url: v.url,
+    httpMethod: v.method,
+    remark: v.remark,
+    contentType: v.contentType,
+    outboundApiParamList: paramList,
+    outboundApiResultList: resultList,
+    paramExample: prettyExample(v.bodyJson),
+    resultExample: prettyExample(v.resultJson)
+  });
+}
+
+/** 把结构树打成人能看的形式 */
+function printTree(title, nodes) {
+  process.stdout.write(`      ${title}:\n`);
+  for (const line of renderTree(nodes, 3)) process.stdout.write(`        ${line}\n`);
+}
+
+/**
+ * 创建并发布 API 资源
+ * 编排：确认连接器 → 组装结构树 → 保存 → 发布准备 → 发布（含路径冲突重试）
+ */
+async function commandApiCreate(cfg, argv) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    process.stdout.write(USAGE + '\n');
+    process.exitCode = 0;
+    return;
+  }
+
+  const cred = loadCredentials();
+  if (!cred || !cred.tokenValue) {
+    throw new Error('未登录或授权已失效，请先执行 auth login');
+  }
+
+  // 步骤 1/4：确认连接器应用
+  const platform = await resolvePlatformRecord(cfg, cred, opts.platform, process.stdout);
+  if (opts.hostId) platform.platformHostId = String(opts.hostId).trim();
+
+  process.stdout.write(`[1/4] 连接器: ${platform.platformName || '(未知名称)'}(${platform.platformId})\n`);
+  if (platform.host) process.stdout.write(`      host = ${platform.host}\n`);
+  if (!platform.platformHostId) {
+    throw new Error(
+      `没有拿到 platformHostId（连接器 ${platform.platformId} 的 hostBOList 为空或未命中）。\n` +
+        `        请用 --host-id <platformHostId> 手工指定，或在平台上先为该连接器配置 host。`
+    );
+  }
+  process.stdout.write(`      platformHostId = ${platform.platformHostId}\n`);
+
+  // 步骤 2/4：组装结构树
+  const v = collect(opts);
+  const body = assemble(v, platform);
+
+  process.stdout.write(`[2/4] 结构组装完成\n`);
+  process.stdout.write(`      apiName  = ${v.apiName}\n`);
+  process.stdout.write(`      url      = ${v.url}${v.pathParams.length ? `（路径参数: ${v.pathParams.join(', ')}）` : ''}\n`);
+  process.stdout.write(`      method   = ${v.method}   contentType = ${v.contentType}\n`);
+  process.stdout.write(`      remark   = ${v.remark}\n`);
+  process.stdout.write(`      query    = ${v.queryParams.length ? v.queryParams.join(', ') : '（无）'}\n`);
+  process.stdout.write(`      header   = ${v.headerParams.length ? v.headerParams.join(', ') : '（无）'}\n`);
+
+  // 字段注释统计：注释应来自接口文档，没给就留空（平台侧后续做 MCP 工具时才有可读的入参说明）
+  const labelCount = ALL_SCOPES.reduce((n, s) => n + v.labels[s].size, 0);
+  process.stdout.write(
+    `      labels   = ${labelCount ? `${labelCount} 条字段注释` : '（无，全部留空；建议用 --labels 按接口文档补上）'}\n`
+  );
+  if (v.labelClipped.length) {
+    const uniq = [];
+    for (const c of v.labelClipped) {
+      if (!uniq.some((u) => u.path === c.path && u.length === c.length)) uniq.push(c);
+    }
+    process.stderr.write(
+      `[warn] 以下字段注释超过 ${MAX_LABEL_LENGTH} 字符，已截断：\n` +
+        uniq.map((c) => `       ${c.scope}:${c.path}（${c.length} 字）`).join('\n') +
+        `\n       请先自行总结到 ${MAX_LABEL_LENGTH} 字以内再提交\n`
+    );
+  }
+
+  printTree('入参结构', body.outboundApiParamList);
+  printTree('出参结构', body.outboundApiResultList);
+
+  if (opts.dryRun) {
+    process.stdout.write(`[3/4] --dry-run，未提交。将发送：\n`);
+    process.stdout.write(`POST {baseUrl}/index/sys/api/v1/platforms/${platform.platformId}/papis/save\n`);
+    process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+    process.stdout.write(`\n（发布阶段还会调用 publish-record + publish，此处不展示）\n`);
+    process.exitCode = 0;
+    return;
+  }
+
+  // 步骤 3/4：保存
+  const saveRes = await authedRequest(
+    cfg,
+    cred,
+    'POST',
+    `/sys/api/v1/platforms/${encodeURIComponent(platform.platformId)}/papis/save`,
+    body
+  );
+  const saveJson = saveRes.json;
+  if (!saveJson || typeof saveJson !== 'object') {
+    throw new Error(`保存失败：接口返回异常（HTTP ${saveRes.status}）${String(saveRes.text).slice(0, 200)}`);
+  }
+  if (saveJson.code !== 200) {
+    if (opts.json) process.stdout.write(JSON.stringify(saveJson, null, 2) + '\n');
+    throw new Error(`保存失败：code=${saveJson.code} msg=${saveJson.msg || '未知错误'}`);
+  }
+
+  const outboundApiId = pickOutboundApiId(saveJson.data);
+  if (!outboundApiId) {
+    throw new Error(
+      `保存接口未返回 outboundApiId：${JSON.stringify(saveJson.data)}\n` +
+        `        无法继续发布，请到平台页面确认该 API 资源是否已生成。`
+    );
+  }
+  process.stdout.write(`[3/4] 保存成功  outboundApiId = ${outboundApiId}\n`);
+
+  if (!opts.publish) {
+    process.stdout.write(`[4/4] --no-publish，跳过发布\n`);
+    process.stdout.write(`\n后续发布：wb api publish --platform ${platform.platformId} --api ${outboundApiId}\n`);
+    if (opts.json) process.stdout.write(JSON.stringify(saveJson, null, 2) + '\n');
+    process.exitCode = 0;
+    return;
+  }
+
+  // 步骤 4/4：发布（含路径冲突重试）
+  const result = await publishWithRetry(
+    cfg,
+    cred,
+    { platformId: platform.platformId, outboundApiId, apiName: v.apiName },
+    {
+      maxRetry: opts.maxRetry,
+      urlSuffix: opts.urlSuffix,
+      log: (s) => process.stdout.write('      ' + s + '\n')
+    }
+  );
+
+  process.stdout.write(`[4/4] 发布成功\n`);
+  process.stdout.write(`      outboundApiId = ${outboundApiId}\n`);
+  process.stdout.write(`      发布路径      = ${result.url}\n`);
+  if (result.flowId) process.stdout.write(`      flowId        = ${result.flowId}\n`);
+  if (result.attempts.length > 1) {
+    process.stdout.write(`      共尝试 ${result.attempts.length} 次（前 ${result.attempts.length - 1} 次路径被占用）\n`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ save: saveJson, publishRecord: result.prep.raw, publish: result.raw }, null, 2) + '\n'
+    );
+  }
+
+  process.stdout.write(`\n复核: wb api list --platform ${platform.platformId} --name ${v.apiName}\n`);
+  process.exitCode = 0;
+}
+
+module.exports = {
+  commandApiCreate,
+  assemble,
+  collect,
+  parseArgs,
+  readJsonSource,
+  normalizeMethod,
+  buildLabelInput,
+  METHODS,
+  LABEL_SCOPE_ALIASES,
+  ALL_SCOPES
+};