Basic 基础服务接入指南

1. 服务概述

Basic 是畅远飞轮平台的基础服务，提供以下核心能力：

• 国际化 (i18n)：词条空间管理、词条翻译、多语言发布、导入导出（JSON/CSV/Excel）
• 项目管理：项目与应用实体管理、项目-应用关联与语言配置
• 租户管理：多租户创建、配置、域名绑定
• 字典管理：字典项目/模块/分组/字典项的 CRUD、版本发布与回滚、草稿对比、资产导入导出
• 存储服务：虚拟存储操作（OSS / CopyParty 适配）
• 内部认证：OIDC 认证、JWT 验证

接口协议：gRPC + REST API

2. 快速接入

2.1 Maven 依赖

轻量客户端（仅接口定义和 DTO）：

<dependency>
    <groupId>com.ginlong</groupId>
    <artifactId>basic-client</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

gRPC 接口包（含 Protobuf Stub）：

<dependency>
    <groupId>com.ginlong</groupId>
    <artifactId>basic-grpc-interface</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2.2 gRPC 客户端配置

在调用方的 application.yaml 中配置 gRPC 通道：

grpc:
  client:
    basic-grpc-server:
      address: 'dns:///basic-service:9090'
      negotiationType: plaintext
      enableKeepAlive: true
      keepAliveTime: 30s
      keepAliveTimeout: 5s

注入 gRPC Stub 示例：

@GrpcClient("basic-grpc-server")
private I18nServiceGrpc.I18nServiceBlockingStub i18nStub;

@GrpcClient("basic-grpc-server")
private ProjectServiceGrpc.ProjectServiceBlockingStub projectStub;

@GrpcClient("basic-grpc-server")
private TenantServiceGrpc.TenantServiceBlockingStub tenantStub;

2.3 认证与租户上下文

REST API 调用时需传递以下 Header：

gRPC 调用时通过 Metadata 传递：

Metadata metadata = new Metadata();
metadata.put(Metadata.Key.of("X-TENANT", Metadata.ASCII_STRING_MARSHALLER), tenantCode);
metadata.put(Metadata.Key.of("X-UID", Metadata.ASCII_STRING_MARSHALLER), userId);

3. gRPC 服务接口

3.1 I18nService

包名： com.ginlong.basic.grpc.i18n

关键 Message 定义：

// 查询项目应用
message FindProjectReqPB {
  string projectCode = 1;  // 项目编码（必填）
  string appCode = 2;      // 应用编码（必填）
}

message FindProjectRespPB {
  string projectCode = 1;
  string appCode = 12;
  string name = 2;
  string description = 3;
  string defaultLangCode = 4;           // 默认语言编码
  repeated string supportLangCodes = 5; // 支持的语言编码列表
  google.protobuf.Struct extraProps = 6;
  google.protobuf.Struct langCodeNameMap = 7; // 语言编码-名称映射
}

// 搜索词条
message SearchTermsReqPB {
  string projectCode = 1;
  string appCode = 12;
  string spaceCode = 2;     // 词条空间编码
  string codeLike = 3;      // 编码模糊匹配
  string codeEqual = 8;     // 编码精确匹配
  string contentLike = 4;   // 内容模糊匹配
  int32 size = 5;           // 每页大小
  int32 pageInx = 6;        // 页码
  repeated string codeLikes = 7; // 批量编码模糊匹配
}

// 词条响应
message TermRespPB {
  string projectCode = 1;
  string appCode = 12;
  string spaceCode = 2;
  string code = 3;
  google.protobuf.Struct content = 4;     // 多语言内容 {langCode: text}
  int64 gmtPublished = 5;                 // 发布时间戳
  int64 gmtSaved = 6;                     // 保存时间戳
  google.protobuf.Struct extraProps = 7;
}

// 导入方法枚举
enum ImportMethodEnumPb {
  UNKNOWN_IMP_METHOD = 0;
  RESET_AND_APPEND = 1;          // 清空后追加
  APPEND_AND_OVERWRITE = 2;      // 追加并覆盖已有
  APPEND_AND_NOT_OVERWRITE = 3;  // 追加但不覆盖已有
}

// 导入导出格式枚举
enum ImportExportTypeEnumPB {
  UNKNOWN_IMP_EXP_TYPE = 0;
  JSON = 1;
  CVS = 2;
  XLS = 3;
}

调用示例：

// 搜索词条
SearchTermsReqPB req = SearchTermsReqPB.newBuilder()
    .setProjectCode("my-project")
    .setAppCode("web")
    .setSpaceCode("common")
    .setSize(20)
    .setPageInx(0)
    .build();
SearchTermsRespPB resp = i18nStub.searchTerms(req);

3.2 ProjectService

包名： com.ginlong.basic.grpc.project

关键 Message 定义：

message FindProjectReqPB {
  string projectCode = 1;  // 项目编码（必填）
}

message ProjectRespPB {
  string code = 1;
  string name = 2;
  string note = 3;
  google.protobuf.Struct publicProp = 4;    // 公开属性
  google.protobuf.Struct internalProp = 5;  // 内部属性
}

message FindProjectAppReqPB {
  string projectCode = 1;  // 项目编码（必填）
  string code = 2;         // 应用编码（必填）
}

message ProjectAppRespPB {
  string code = 1;
  string projectCode = 2;
  string name = 3;
  string note = 4;
  string endType = 5;            // 端类型
  repeated string endTag = 6;    // 端标签
  bool isDefault = 7;            // 是否默认应用
  bool isVirtual = 8;            // 是否虚拟应用
  google.protobuf.Struct publicProp = 9;
  google.protobuf.Struct internalProp = 10;
}

调用示例：

// 查询项目
FindProjectReqPB req = FindProjectReqPB.newBuilder()
    .setProjectCode("my-project")
    .build();
ProjectRespPB resp = projectStub.findProject(req);

3.3 TenantService

包名： com.ginlong.basic.grpc.tenant

关键 Message 定义：

message FindTenantReqPB {
  string tenantCode = 1;  // 租户编码（必填）
}

message FindTenantByHostReqPB {
  string host = 1;  // 域名（必填）
}

message TenantRespPB {
  string code = 1;
  string name = 2;
  repeated string hosts = 3;          // 绑定域名列表
  string countryRegionCode = 4;       // 国家/地区编码
  int32 status = 5;                   // 状态
  google.protobuf.Struct contactInfo = 6; // 联系信息
  repeated TenantConfRespPB confs = 7;    // 租户配置列表
}

message TenantConfRespPB {
  string tenantCode = 1;
  string projectCode = 2;
  string bizType = 3;      // 业务类型
  string confKey = 4;      // 配置键
  string confValue = 5;    // 配置值
  int32 isPrivate = 6;     // 是否私有
  int32 status = 7;
  string note = 8;
}

调用示例：

// 按域名查询租户
FindTenantByHostReqPB req = FindTenantByHostReqPB.newBuilder()
    .setHost("app.example.com")
    .build();
TenantRespPB resp = tenantStub.findTenantByHost(req);

4. REST API 接口

4.1 国际化管理 (i18n)

基础路径前缀： internal/i18nmng-api/

语言管理

项目应用管理

词条空间管理

基础路径： internal/i18nmng-api/project/{projectCode}/app/{appCode}/termspace

词条管理

基础路径： internal/i18nmng-api/project/{projectCode}/app/{appCode}/termspace/{spaceCode}/term

生产使用接口（无需 internal 前缀）

基础路径： i18nmng-api/project/termspace

curl 示例：

# 搜索词条空间
curl -X GET 'http://basic-service/internal/i18nmng-api/project/my-project/app/web/termspace/page?size=20&pageInx=0' \
  -H 'X-TENANT: tenant001'

# 创建词条
curl -X POST 'http://basic-service/internal/i18nmng-api/project/my-project/app/web/termspace/common/term' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"code":"btn.submit","content":{"zh_CN":"提交","en_US":"Submit"}}'

# 获取翻译版本信息（生产使用）
curl -X GET 'http://basic-service/i18nmng-api/project/termspace/project/my-project/app/web/translation/version' \
  -H 'X-TENANT: tenant001'

4.2 项目管理

基础路径前缀： project-api/project

curl 示例：

curl -X GET 'http://basic-service/project-api/project' \
  -H 'X-TENANT: tenant001'

4.3 租户管理

基础路径前缀： internal/tenant-api/

租户 CRUD

租户配置

curl 示例：

# 按编码查询租户
curl -X GET 'http://basic-service/internal/tenant-api/tenant/tenant001' \
  -H 'X-TENANT: tenant001'

# 创建租户配置
curl -X POST 'http://basic-service/internal/tenant-api/tenant-conf' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"tenantCode":"tenant001","projectCode":"proj1","bizType":"config","confKey":"theme","confValue":"dark"}'

4.4 字典管理

字典项目管理

基础路径： dictionary-api/project

字典模块管理

基础路径： internal/dictionary-api/module

字典分组管理

基础路径： internal/dictionary-api/group

字典项管理

基础路径： internal/dictionary-api/item

字典统一查询（生产使用）

基础路径： dictionary-api/query

字典发布版本管理

基础路径： internal/dictionary-api/publish

字典草稿对比

基础路径： internal/dictionary-api/diff

字典资产管理

基础路径： internal/dictionary-api/asset

curl 示例：

# 统一查询字典（生产使用）
curl -X GET 'http://basic-service/dictionary-api/query?projectCodes=proj1&groupCodes=gender,status' \
  -H 'X-TENANT: tenant001'

# 发布字典
curl -X POST 'http://basic-service/internal/dictionary-api/publish/proj1' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"remark":"v2 release"}'

# 查询草稿差异
curl -X GET 'http://basic-service/internal/dictionary-api/diff/proj1' \
  -H 'X-TENANT: tenant001'

4.5 内部认证

基础路径前缀： internal/auth-api/

curl 示例：

curl -X GET 'http://basic-service/internal/auth-api/user/info' \
  -H 'Authorization: Bearer <token>'

5. 客户端 SDK 接口

basic-client 模块提供以下 ClientService 接口，供域内服务直接依赖调用。

5.1 I18n 域

I18nTermClientService — 词条管理

• searchTerms(SearchTermsQuery) → SearchTermsDto
• findTerm(FindTermQuery) → TermDto
• saveTerm(SaveTermCmd) → SaveTermDto
• deleteTerm(DeleteTermCmd) → DeleteTermDto

I18nLangClientService — 语言管理

• listLangs(ListLangQuery) → ListLangDto
• saveLang(SaveLangCmd) → SaveLangDto
• deleteLang(DeleteLangCmd) → DeleteLangDto

I18nTermSpaceClientService — 词条空间管理

• searchTermSpaces(SearchTermSpacesQuery) → SearchTermSpacesDto
• findTermSpace(FindTermSpaceQuery) → TermSpaceDto
• saveTermSpace(SaveTermSpaceCmd) → SaveTermSpaceDto
• copyTermSpace(CopyTermSpaceCmd) → CopyTermSpaceDto
• deleteTermSpace(DeleteTermSpaceCmd) → DeleteTermSpaceDto
• publishTermSpace(PublishTermSpaceCmd) → PublishTermSpaceDto
• importTerms(ImportTermsCmd) → ImportTermsDto
• exportTerms(ExportTermsQuery) → ExportTermsDto
• exportFile(ExportFileCmd) → ExportFileDto
• translationVersion(TranslationVersionQuery) → TranslationVersionDto
• 更多方法见源码

I18nProjectAppClientService — 项目应用管理

• findProjectApp(FindProjectAppQuery) → ProjectAppDto
• listProjectApps(ListProjectAppsQuery) → ListProjectAppsDto
• saveProjectApp(SaveProjectAppCmd) → SaveProjectAppDto
• deleteProjectApp(DeleteProjectAppCmd) → DeleteProjectsAppDto
• listProjectAppSupportLang(ListProjectAppSupportLang) → List<SimpleLangDto>

5.2 Project 域

ProjectClientService — 项目管理

• search(ProjectSearchDto) → List<ProjectDto>

ProjectAppClientService — 项目应用管理

• search(ProjectAppSearchDto) → List<ProjectAppDto>
• find(ProjectAppFindDto) → ProjectAppDto

5.3 Tenant 域

TenantClientService — 租户查询

• findByCode(String tenantCode) → TenantDto
• findByHost(String host) → TenantDto

TenantManageService — 租户管理

• create(TenantDto) → TenantDto
• update(Long id, ...) → TenantDto
• delete(Long id) → void
• findByCode(String code) → TenantDto
• search(String name, int page, int size) → SearchTenantsDto

TenantConfManageService — 租户配置管理

• create(TenantConfDto) → TenantConfDto
• update(Long id, TenantConfDto) → TenantConfDto
• delete(Long id) → void
• search(String tenantCode, String projectCode, String bizType, int page, int size) → SearchTenantConfsDto

5.4 Dictionary 域

DictionaryProjectClientService — 字典项目

• create(String projectCode) → DictionaryProjectDto
• delete(Long id) → void
• page(int page, int size) → SearchDictionaryProjectsDto

DictionaryModuleClientService — 字典模块

• create(DictionaryModuleDto) → DictionaryModuleDto
• update(Long id, String moduleName, String description) → DictionaryModuleDto
• delete(Long id) → void
• search(String projectCode, String moduleName, int page, int size) → SearchDictionaryModulesDto

DictionaryGroupClientService — 字典分组

• create(DictionaryGroupDto) → DictionaryGroupDto
• update(Long id, String groupName, String type, String description) → DictionaryGroupDto
• delete(Long id) → void
• findByGroupCode(String projectCode, String groupCode) → DictionaryGroupDto
• search(String projectCode, String groupName, int page, int size) → SearchDictionaryGroupsDto
• bindModule(String groupCode, String moduleCode) → void
• unbindModule(String groupCode, String moduleCode) → void

DictionaryItemClientService — 字典项

• create(DictionaryItemDto) → DictionaryItemDto
• batchCreate(List<DictionaryItemDto>) → List<DictionaryItemDto>
• update(Long id, DictionaryItemDto) → DictionaryItemDto
• batchUpdate(List<DictionaryItemDto>) → List<DictionaryItemDto>
• delete(Long id) → void
• setEnabled(Long id, boolean enabled) → void

DictionaryQueryClientService — 字典查询

• query(List<String> projectCodes, List<String> moduleCodes, List<String> groupCodes) → Map<String, DictionaryGroupDataDto>
• queryPublished(...) → Map<String, ProjectQueryDataDto>

DictionaryPublishClientService — 字典发布

• publish(String projectCode, String remark) → DictionaryPublishVersionDto
• rollback(String projectCode, int targetVersionNumber) → DictionaryPublishVersionDto
• listVersions(String projectCode, int page, int size) → SearchPublishVersionsDto
• getVersionDetail(String projectCode, int versionNumber) → DictionaryPublishVersionDto
• getActiveVersionNumber(String projectCode) → Integer
• listPublishedProjects() → List<ProjectPublishSummaryDto>

DictionaryDiffClientService — 字典对比

• diff(String projectCode) → DiffResult

DictionaryAssetClientService — 字典资产

• export(String projectCode, Integer versionNumber) → ExportPackage
• importAsset(String projectCode, ExportPackage, boolean strictParent) → ImportResultDto
• clearDraft(String projectCode) → ClearResultDto

5.5 Storage 域

PhysicalStorageOperationClientService — 物理存储操作

• upload(String bucketName, String key, Map<String, String> metadata, InputStream inputStream) → void
• deleteBatch(String bucketName, String keyPrefix) → void
• exist(String bucketName, List<String> keys) → Map<String, Boolean>

6. 配置参考

6.1 必填配置

6.2 可选配置

6.3 存储配置（按需）

6.4 i18n 存储配置

6.5 OIDC 认证配置

7. 最佳实践

• 超时配置：gRPC 调用建议设置 5s 超时，导入导出等大文件操作可放宽至 30s
• 重试策略：查询类接口可安全重试（幂等），写入类接口需确认幂等性后再重试
• 缓存策略：租户信息、项目信息变更频率低，建议本地缓存 5 分钟；字典查询接口支持版本号增量更新，利用 projectCode@versionNumber 格式减少全量拉取
• 多租户：所有请求必须携带 X-TENANT Header，gRPC 通过 Metadata 传递