支持生成、发布 Typescript SDK

2025-08-21 04:36:13 +08:00
parent cfde112832
commit cebac01716
6 changed files with 232 additions and 5 deletions
--- a/47
+++ b/47
@@ -5,6 +5,8 @@ BUF := buf
 GEN_DIR := gen
 GO_MOD := git.0yue.com/shenxianhe/sdk
 GO_SDK_REPO := https://git.0yue.com/shenxianhe/sdk.git
+TS_PACKAGE_NAME := @shenxianhe/sdk
+TS_SDK_REPO := https://git.0yue.com/shenxianhe/sdk-ts.git

 # 默认目标 - 显示帮助信息
 .DEFAULT_GOAL := help
@@ -17,9 +19,9 @@ generate: common-gen language-gen
 .PHONY: common-gen
 common-gen: lint clean generate-pb

-# 语言特定处理部分（目前只有go）
+# 语言特定处理部分
 .PHONY: language-gen
-language-gen: init-go generate-go-readme
+language-gen: init-go generate-go-readme init-ts generate-ts-readme

 # 执行buf lint检查
 .PHONY: lint
@@ -45,7 +47,23 @@ init-go:
 	@echo "在$(GEN_DIR)/go目录初始化go module..."
 	cd $(GEN_DIR)/go && go mod init $(GO_MOD) && go mod tidy

-# 发布命令 - 目前只处理go语言
+# TypeScript特定初始化
+.PHONY: init-ts
+init-ts:
+	@echo "在$(GEN_DIR)/ts目录初始化npm项目..."
+	@mkdir -p $(GEN_DIR)/ts
+	@echo "创建package.json文件..."
+	@VERSION=$$(cat version.txt) && \
+	sed -e "s|{{TS_PACKAGE_NAME}}|$(TS_PACKAGE_NAME)|g" \
+	-e "s|{{VERSION}}|$$VERSION|g" \
+	-e "s|{{TS_SDK_REPO}}|$(TS_SDK_REPO)|g" \
+	templates/ts-package.json.tpl > $(GEN_DIR)/ts/package.json
+	@echo "创建tsconfig.json文件..."
+	@echo '{"compilerOptions":{"target":"ES2019","module":"CommonJS","strict":true,"esModuleInterop":true,"skipLibCheck":true,"forceConsistentCasingInFileNames":true},"include":["./"]}' > $(GEN_DIR)/ts/tsconfig.json
+	@echo "安装必要的依赖..."
+	@cd $(GEN_DIR)/ts && npm install
+
+# 发布命令
 .PHONY: publish
 publish:
 	@echo "开始发布流程..."
@@ -55,7 +73,7 @@ publish:
 	@echo "正在生成新版本号..."
 	@script/get_next_version.sh
 	# 调用各个语言的发布目标
-	@$(MAKE) publish-go
+	@$(MAKE) publish-go publish-ts

 # Go语言代码发布子命令
 .PHONY: publish-go
@@ -64,6 +82,15 @@ publish-go: generate
 	# 确保git发布脚本可执行并调用git发布脚本（内部会自己获取版本号）
 	chmod +x script/publish-git.sh && script/publish-git.sh "$(GO_SDK_REPO)" "$(GEN_DIR)/go"

+# TypeScript代码发布子命令
+.PHONY: publish-ts
+publish-ts: generate
+	@echo "准备发布TypeScript SDK到npm仓库..."
+	# 获取版本号
+	@VERSION=$$(cat version.txt) && \
+	chmod +x script/publish-npm.sh && \
+	script/publish-npm.sh "$(TS_PACKAGE_NAME)" "$$VERSION" "$(GEN_DIR)/ts"
+
 # 生成Go SDK的README文件
 .PHONY: generate-go-readme
 generate-go-readme:
@@ -71,6 +98,13 @@ generate-go-readme:
 	@mkdir -p $(GEN_DIR)/go
 	@cp templates/go-sdk-readme.md $(GEN_DIR)/go/README.md

+# 生成TypeScript SDK的README文件
+.PHONY: generate-ts-readme
+generate-ts-readme:
+	@echo "生成TypeScript SDK的README文件..."
+	@mkdir -p $(GEN_DIR)/ts
+	@cp templates/ts-sdk-readme.md $(GEN_DIR)/ts/README.md
+
 # 帮助信息
 .PHONY: help
 help:
@@ -80,7 +114,10 @@ help:
 	@echo "  clean           - 删除 $(GEN_DIR) 目录"
 	@echo "  generate-pb     - 使用 $(BUF) generate 生成 protobuf 文件"
 	@echo "  init-go         - 在 $(GEN_DIR)/go 目录初始化go module"
+	@echo "  init-ts         - 在 $(GEN_DIR)/ts 目录初始化npm项目"
 	@echo "  generate-go-readme - 生成Go SDK的README文件，包含使用示例和版本说明"
-	@echo "  publish         - 发布生成的 protobuf 代码"
+	@echo "  generate-ts-readme - 生成TypeScript SDK的README文件，包含使用示例和版本说明"
+	@echo "  publish         - 发布生成的 protobuf 代码（Go和TypeScript）"
 	@echo "  publish-go      - 发布go语言代码到 $(GO_SDK_REPO) 仓库，并自动打tag"
+	@echo "  publish-ts      - 发布TypeScript SDK到npm仓库，需先设置NPM_AUTH_TOKEN环境变量"
 	@echo "  help            - 显示此帮助信息"
--- a/README.md
+++ b/README.md
@@ -25,6 +25,8 @@ proto/

 本项目使用多个工具进行 Protocol Buffers 的管理、构建和代码生成。请安装以下工具：

+1. go 相关工具
+
 ```bash
 go install github.com/bufbuild/buf/cmd/buf@latest
 go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
@@ -32,6 +34,18 @@ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
 go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
 ```

+如果安装后依然提示找不到命令，需要将 go 的 bin 目录添加到 PATH 中。
+如果是使用 brew 安装的 go，可以执行 `brew unlink go && brew link go` 来解决。
+
+2. node 相关工具
+
+```bash
+npm install -g @bufbuild/protoc-gen-es
+```
+
+如果安装后依然提示找不到命令，需要将 npm 的 bin 目录添加到 PATH 中。
+如果是使用 brew 安装的 node，可以执行 `brew unlink node && brew link node` 来解决。
+
 ### 检查语法

 ```bash
--- a/buf.gen.yaml
+++ b/buf.gen.yaml
@@ -6,3 +6,7 @@ plugins:
  - local: protoc-gen-connect-go
    out: gen/go
    opt: paths=source_relative
+  - local: protoc-gen-es
+    out: gen/ts
+    include_imports: true
+    opt: target=ts
--- a/script/publish-npm.sh
+++ b/script/publish-npm.sh
@@ -0,0 +1,95 @@
+#!/bin/bash
+
+# npm发布脚本
+# 参数1: 包名
+# 参数2: 版本号
+# 参数3: 工作目录
+
+# 确保提供了必要的参数
+if [ $# -lt 3 ]; then
+  echo "错误：缺少必要参数"
+  echo "用法：$0 <包名> <版本号> <工作目录>"
+  exit 1
+fi
+
+PACKAGE_NAME="$1"
+VERSION="$2"
+WORK_DIR="$3"
+
+# 检查工作目录是否存在
+if [ ! -d "$WORK_DIR" ]; then
+  echo "错误：工作目录 $WORK_DIR 不存在"
+  exit 1
+fi
+
+# 切换到工作目录
+cd "$WORK_DIR"
+
+# 设置npm注册表
+echo "设置npm注册表..."
+npm config set @shenxianhe:registry=https://git.0yue.com/api/packages/shenxianhe/npm/
+
+
+
+# 配置npm认证（如果提供了环境变量）
+configure_npm_auth() {
+  # 如果设置了 SHENXIANHE_AUTH_TOKEN 变量，则配置npm
+  if [ -n "$SHENXIANHE_AUTH_TOKEN" ]; then
+    echo "检测到 SHENXIANHE_AUTH_TOKEN 环境变量，配置npm认证..."
+    npm config set -- '//git.0yue.com/api/packages/shenxianhe/npm/:_authToken' "$SHENXIANHE_AUTH_TOKEN"
+  fi
+  
+  # 无论是否设置了环境变量，都继续执行（因为可能之前已经配置过npm）
+  echo "正在使用当前npm配置进行认证..."
+}
+
+# 显示认证错误提示信息
+display_auth_error() {
+  echo "提示：如果是认证失败，请尝试设置环境变量：export SHENXIANHE_AUTH_TOKEN=your_access_token"
+}
+
+# 调用函数配置npm认证（如果有环境变量）
+configure_npm_auth
+
+# 检查包是否已存在
+check_package_exists() {
+  echo "检查包 $PACKAGE_NAME@$VERSION 是否已存在..."
+  # 使用npm view命令检查包是否存在
+  if npm view "$PACKAGE_NAME@$VERSION" --registry=https://git.0yue.com/api/packages/shenxianhe/npm/ > /dev/null 2>&1; then
+    return 0  # 包已存在
+  else
+    return 1  # 包不存在
+  fi
+}
+
+# 如果包已存在，询问是否删除
+if check_package_exists; then
+  echo "警告：包 $PACKAGE_NAME@$VERSION 已存在"
+  echo "是否要先删除现有包？(y/n)"
+  read -r answer
+  if [ "$answer" = "y" ] || [ "$answer" = "Y" ]; then
+    echo "删除现有包 $PACKAGE_NAME@$VERSION..."
+    npm unpublish --force "$PACKAGE_NAME@$VERSION" --registry=https://git.0yue.com/api/packages/shenxianhe/npm/
+    if [ $? -ne 0 ]; then
+      echo "错误：删除包失败"
+      display_auth_error
+      exit 1
+    fi
+  else
+    echo "取消发布操作"
+    exit 1
+  fi
+fi
+
+# 发布包
+echo "发布包 $PACKAGE_NAME@$VERSION..."
+npm publish --registry=https://git.0yue.com/api/packages/shenxianhe/npm/
+
+# 检查发布是否成功
+if [ $? -eq 0 ]; then
+  echo "成功发布包 $PACKAGE_NAME@$VERSION 到 npm 仓库"
+else
+    echo "错误：发布包失败"
+    display_auth_error
+    exit 1
+  fi
--- a/templates/ts-package.json.tpl
+++ b/templates/ts-package.json.tpl
@@ -0,0 +1,21 @@
+{
+  "name": "{{TS_PACKAGE_NAME}}",
+  "version": "{{VERSION}}",
+  "description": "自动生成的TypeScript SDK，用于与shenxianhe服务进行交互",
+  "repository": {
+    "type": "git",
+    "url": "{{TS_SDK_REPO}}"
+  },
+  "keywords": [
+    "protobuf",
+    "typescript",
+    "sdk",
+    "shenxianhe"
+  ],
+  "author": "神仙盒团队",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.7.0"
+  }
+}
--- a/templates/ts-sdk-readme.md
+++ b/templates/ts-sdk-readme.md
@@ -0,0 +1,56 @@
+## 项目简介
+
+这是由 protobuf 自动生成的 TypeScript SDK，用于与 shenxianhe 服务进行交互。
+
+## SDK 版本与 API 版本的区别
+
+**SDK 版本**：
+
+- 由 Git tag 管理，格式为 vX.Y.Z
+- 表示生成的 SDK 代码的版本号
+- 每次重新生成并发布代码时会自增
+
+**API 版本**：
+
+- 体现在 proto 文件路径中，如 v1、v2 等
+- 表示服务接口的版本号
+- 由服务端定义和维护
+
+两个版本号是相互独立的概念，同一 API 版本可能对应多个 SDK 版本。
+
+## 使用示例
+
+```typescript
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-web";
+import { AccountService, AuthenticationType } from "@shenxianhe/sdk/account/v1/account_pb";
+
+const transport = createConnectTransport({
+  baseUrl: "https://your-service-url",
+});
+const client = createClient(AccountService, transport);
+
+const res = await client.auth({
+  authType: AuthenticationType.PHONE,
+  authId: '13800138000',
+  credential: '123456',
+});
+console.log(res.sentence);
+```
+
+### 注意事项
+
+- 本版本 SDK 仅包含 protobuf 类型定义，不包含服务客户端实现
+- 如需服务客户端功能，您需要：
+  1. 安装@bufbuild/connect-es 和@bufbuild/connect-web 库
+  2. 使用 protoc-gen-connect-es 插件重新生成代码
+  3. 参考 Buf 官方文档实现客户端
+
+## 注意事项
+
+- 本 SDK 由代码自动生成，请勿手动修改
+- 如有任何问题，请联系服务提供方
+
+## 版权信息
+
+© 2025 神仙盒团队. All rights reserved.