Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ bash shared/scripts/regenerate-all.sh

这一步会依次跑:
1. `shared/scripts/gen-route-meta.mjs`——解析 `x-qdmp-token-required`/`x-qdmp-auth-scheme`/`x-error-codes` 等自定义扩展字段(三个官方 codegen 工具都不认它们),生成 `shared/generated/{route-meta,error-codes}.json`。
2. Node:`openapi-typescript` 生成 `node/src/generated/schema.d.ts`,再跑 `node/scripts/gen-route-meta.mjs` 同步路由元数据/错误码到 TS。
2. Node.js:`openapi-typescript` 生成 `node/src/generated/schema.d.ts`,再跑 `node/scripts/gen-route-meta.mjs` 同步路由元数据/错误码到 TS。
3. Java:`openapi-generator-cli`(`--library=resttemplate`,models-only)生成 `java/generated/`,再跑 `java/scripts/gen-route-meta.mjs` 同步。
4. Go:`oapi-codegen` 生成 `go/generated/types.gen.go`。

Expand All @@ -29,7 +29,7 @@ CI 的 `generate-check.yml` 会重新跑一遍这个脚本并 `git diff --exit-c
## 构建 / Lint

```bash
# Node
# Node.js
cd node && npm ci && npm run typecheck && npm run lint && npm run build

# Java
Expand All @@ -50,7 +50,7 @@ cd go && gofmt -l . && go vet ./... && staticcheck ./...
## 测试

```bash
# Node
# Node.js
cd node && npm test

# Java
Expand All @@ -60,13 +60,13 @@ cd java && ./gradlew test
cd go && go test ./...
```

三端测试都是 mock HTTP(Node 用 undici `MockAgent`,Java 用 `MockWebServer`,Go 用 `httptest`),不依赖真实网络或真实凭证。
三端测试都是 mock HTTP(Node.js 用 undici `MockAgent`,Java 用 `MockWebServer`,Go 用 `httptest`),不依赖真实网络或真实凭证。

## 覆盖率报告

三端覆盖率工具都是各语言原生自带,纯本地生成,不需要额外依赖或联网:

- **Node**:`cd node && npm run test:coverage`(Node 内置 test runner 的 `--experimental-test-coverage`),终端直接输出逐文件行/分支/函数覆盖率表格。
- **Node.js**:`cd node && npm run test:coverage`(Node.js 内置 test runner 的 `--experimental-test-coverage`),终端直接输出逐文件行/分支/函数覆盖率表格。
- **Java**:`cd java && ./gradlew test jacocoTestReport`(Gradle 内置 JaCoCo 插件),报告在 `java/build/reports/jacoco/test/html/index.html`;已排除 `generated/` 下的 openapi-generator 产物,避免稀释覆盖率数字。
- **Go**:`cd go && go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out -o coverage.html`;`go/generated` 是纯数据结构,0% 覆盖率是预期结果,不代表未测试。

Expand All @@ -76,14 +76,14 @@ cd go && go test ./...

| 语言 | 版本号位置 | tag 格式 | 发布方式 |
|---|---|---|---|
| Node | `node/package.json` 的 `version` | `node/vX.Y.Z` | `publish-node.yml`:校验版本号一致 → test/build → `npm publish` |
| Node.js | `node/package.json` 的 `version` | `node/vX.Y.Z` | `publish-node.yml`:校验版本号一致 → test/build → `npm publish` |
| Java | `java/build.gradle.kts` 的 `version` | `java/vX.Y.Z` | `publish-java.yml`:校验版本号一致且非 `-SNAPSHOT` → test → `publishToMavenCentral` |
| Go | 无版本文件,tag 即版本 | `go/vX.Y.Z` | 无需发布 workflow,Go module proxy 被动抓取 tag(`go/` 子目录 module,tag 必须带 `go/` 前缀) |

发版流程:改对应版本号文件、合并到 main,再打 tag push 上去,CI 校验一致后自动发布。

发布前置条件(尚未配置):

- **Node**:仓库 secret `NPM_TOKEN`;包名是 scoped 包 `@qdmp/qdmp-server-sdk`,`@qdmp` 这个 npm org 目前还不存在(已查 `registry.npmjs.org` 确认未注册),发布前需要先创建并让 token 归属的账号拥有该 org 的发布权限。
- **Node.js**:仓库 secret `NPM_TOKEN`;包名是 scoped 包 `@qdmp/qdmp-server-sdk`,`@qdmp` 这个 npm org 目前还不存在(已查 `registry.npmjs.org` 确认未注册),发布前需要先创建并让 token 归属的账号拥有该 org 的发布权限。
- **Java**:仓库 secrets `MAVEN_CENTRAL_USERNAME`/`MAVEN_CENTRAL_PASSWORD`/`GPG_SIGNING_KEY`/`GPG_SIGNING_PASSWORD`;且需要在 Central Portal 手动 Add Namespace 验证 `io.github.echotechfe`(组织命名空间不能走 GitHub OAuth 自动验证)。
- **push 到 GitHub**:远程 `origin` 已配置但尚未推送。
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# qdmp-server-sdk

[千岛(qdmp)OpenAPI](https://open.qiandao.com/docs/api/auth-token) 官方 Server SDK,[Node](#node)、[Java](#java)、[Go](#go) 三端实现,统一 token 生命周期管理 + 类型安全的业务接口封装。
[千岛小程序开放平台 OpenAPI](https://open.qiandao.com/docs/api/auth-token) 官方 Server SDK,[Node.js](#nodejs)、[Java](#java)、[Go](#go) 三端实现,统一 token 生命周期管理 + 类型安全的业务接口封装。

## Node
## Node.js

```bash
npm install @qdmp/qdmp-server-sdk
Expand Down Expand Up @@ -112,7 +112,7 @@ appToken, err := client.Auth.GetAccessToken(ctx)

| 语言 | HTTP 传输 | JSON |
|---|---|---|
| Node | 内置全局 `fetch`(`undici` 仅作为开发依赖,提供测试用的 `MockAgent`) | 内置 `JSON` |
| Node.js | 内置全局 `fetch`(`undici` 仅作为开发依赖,提供测试用的 `MockAgent`) | 内置 `JSON` |
| Java | OkHttp(`okhttp3`) | Jackson |
| Go | 标准库 `net/http` | 标准库 `encoding/json` |

Expand Down
2 changes: 1 addition & 1 deletion go/doc.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Package qdmp is the Go Server SDK for 千岛 (qdmp) OpenAPI.
// Package qdmp is the Go Server SDK for 千岛小程序开放平台 OpenAPI.
//
// Construct a client with NewClient, exchange an app-level access token via
// Client.Auth.GetAccessToken (cached and single-flight refreshed
Expand Down
2 changes: 1 addition & 1 deletion java/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ mavenPublishing {

pom {
name.set("qdmp-server-sdk")
description.set("千岛(qdmp)OpenAPI 官方 Java Server SDK")
description.set("千岛小程序开放平台 OpenAPI 官方 Java Server SDK")
url.set("https://github.com/EchoTechFE/qdmp-server-sdk")
licenses {
license {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
/*
* 千岛开放平台 API(qdmp OpenAPI)
* 千岛(qdmp)对外 OpenAPI 定义,作为 Node/Java/Go 三端 SDK 类型生成与路由元数据生成的单一真源。逐条核对官方接口文档,并结合真实测试账号的实测结果订正(详见各字段 description 中的“实测确认”标注)。
*
* The version of the OpenAPI document: 1.0.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
* Code generated by openapi-generator from shared/openapi.yaml. DO NOT EDIT.
*/


Expand Down
Loading
Loading