proposal.md 3.1 KB
状态（2026-04-18 立项）：提案阶段，未实施 优先级：高。与
add-mjava-pro并行。
Why
mjava 基座沉淀了大量通用能力：HTTP 请求封装（UtilHttp）、Token 缓存（UtilToken）、JPA + QueryDSL、统一响应体 McR、多数据源、TraceId 链路 等。目前这些能力只能被"引入 mjava 依赖"的 Java 子项目（mcli/shunfeng/guangming）使用。
但实际业务中常遇到：
- 非 Java 系统（Node.js / Python / PHP 宜搭连接器 / 低代码平台）需要调用钉钉/宜搭 API，每个系统重复实现鉴权 + HTTP + token 缓存，浪费且容易出错
- 前端侧业务（宜搭自定义页面 JSX）也希望复用后端对接能力，不想在前端暴露 appSecret
- 实习/新人项目没必要为了调用一次钉钉 API 就起一个完整的 mjava 子项目
需要把 mjava 基座能力"服务化"——通过 mjava-com 子模块对外开放 REST API，外部系统只要通过鉴权就能直接调用钉钉/宜搭/飞书等底层接口，无需引入 mjava 代码。
What Changes
新增子模块 mjava-com/，具备：
- 统一入口 API：
/api/com/{vendor}/{action}（如POST /api/com/dingtalk/user.get）转发到基座 Client 方法 - 调用方鉴权：从宜搭"权限表单"（formUuid 配置在
application.yml）查询被授权的调用方白名单，按 apiKey + signature 验签 - 审计日志：每次调用打完整审计（调用方 ID + vendor + action + latency + success）
- 限流/熔断：按调用方维度做基础限流（避免某个外部系统打爆第三方配额）；Phase 1 用本地
RateLimiter，不引入 Sentinel/Resilience4j - Vendor 暴露白名单：不是所有 Client 方法都自动开放，需要在
application.yml显式声明哪些{vendor}.{action}可被 com 调用
Capabilities
New Capabilities
baas-gateway：BaaS 风格的后端即服务网关，把 mjava Client 能力以 REST 开放caller-registry：外部调用方注册中心（宜搭权限表单）
Modified Capabilities
Impact
- 新增模块：
mjava-com/（独立 jar，默认端口 9020，context-path/api/com） - 新增代码（预计）：
CallerAuthInterceptor.java（apiKey + signature 验签）CallerRegistryService.java（查宜搭权限表单）GatewayController.java（路由/{vendor}/{action}到基座 Client）ActionWhitelistConfig.java（vendor.action 白名单）- 简单本地限流
CallerRateLimiter.java
- 基座影响：零（com 作为 facade 调基座现有 Client）
- 外部调用方：简化 — 只需 apiKey + signature + JSON body 发 POST 即可
Non-Goals
- ❌ 不做 OpenAPI / Swagger 规范（第一阶段人工维护接口文档；若需要再单独提案）
- ❌ 不做计费 / 配额套餐（Phase 1 固定限流即可）
- ❌ 不做 OAuth2 授权（apiKey + HMAC 签名足够内部场景；跨组织再评估）
- ❌ 不引入 API Gateway 中间件（Kong / APISIX / Spring Cloud Gateway 等）
- ❌ 不做请求录制回放（可测性工作，独立专项）