library/simapi-cj
1
0
Fork 0
Code Pull Requests Actions Packages Activity

修正了部分lint

Browse Source
This commit is contained in:
xrain
2026-09-01 20:31:26 +08:00
parent 73e770db80
commit eed230aab0
15 changed files with 91 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -49
View File
@@ -368,25 +368,25 @@ SimApiExtensions.addSimApi(builder) { options =>
}
```
| 方法 | 说明 |
|------|------|
| `getUploadUrl(path, expire=7200)` | 上传预签名 URL，返回 `GetUploadUrlResponse(UploadUrl, DownloadUrl, Path)` |
| `getDownloadUrl(path, expire=600)` | 下载预签名 URL |
| `uploadFile(path, data, contentType="image/png")` | 直接 PUT 上传（字节数组） |
| `deleteFiles(paths)` | 批量删除对象（S3 原生 DeleteObjects，一次请求删多个） |
| `fullUrl(path)` / `getUrl(path)` | 补全访问 URL（`~/` 前缀依赖请求上下文） |
| `getPath(url)` | 从 URL 还原相对路径（去掉 Endpoint/Bucket 或 ServeUrl 前缀） |
| 方法 | 说明 |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| `getUploadUrl(path, expire=7200)` | 上传预签名 URL，返回 `GetUploadUrlResponse(UploadUrl, DownloadUrl, Path)` |
| `getDownloadUrl(path, expire=600)` | 下载预签名 URL |
| `uploadFile(path, data, contentType="image/png")` | 直接 PUT 上传（字节数组） |
| `deleteFiles(paths)` | 批量删除对象（S3 原生 DeleteObjects，一次请求删多个） |
| `fullUrl(path)` / `getUrl(path)` | 补全访问 URL（`~/` 前缀依赖请求上下文） |
| `getPath(url)` | 从 URL 还原相对路径（去掉 Endpoint/Bucket 或 ServeUrl 前缀） |
> 说明：桶不存在时自动创建（静态守卫只执行一次）；
> 预签名与上传使用 AWS SigV4（HMAC-SHA256 基于 stdx SHA256 自实现），已用 AWS 官方测试向量验证签名正确。
### 6. 内置路由（UseSimApi 自动注册）
| 路由 | 方法 | 条件 | 说明 |
| ----------------- | -------- | ---------------------------- | -------------------------- |
| `/user/info` | POST | `enableSimApiAuth` | 需登录，返回 LoginInfo |
| `/auth/logout` | POST | `enableSimApiAuth` | 退出登录 |
| `/exception/{code}` | GET | 始终 | 错误反馈（抛 SimApiException，不出现在文档中） |
| 路由 | 方法 | 条件 | 说明 |
| ------------------- | ---- | ------------------ | ---------------------------------------------- |
| `/user/info` | POST | `enableSimApiAuth` | 需登录，返回 LoginInfo |
| `/auth/logout` | POST | `enableSimApiAuth` | 退出登录 |
| `/exception/{code}` | GET | 始终 | 错误反馈（抛 SimApiException，不出现在文档中） |
路由路径可自定义（`configureSimApiRoute`）：
@@ -427,11 +427,11 @@ SimApiExtensions.addSimApi(builder) { options =>
}
```
| 类 | 说明 |
|----|------|
| `SimApiAuthClient` | `SimApiHttpClient` 子类，凭证取 AuthCenterOptions |
| `SimApiAuthCenter` | 群组/Profile/内部应用/系统登录/安全验证等 12 个接口 + `VerifySign` |
| `SimApiAuthIam` | 注册权限 / 获取权限标识 / 校验权限（无权限抛 403） |
| 类 | 说明 |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `SimApiAuthClient` | `SimApiHttpClient` 子类，凭证取 AuthCenterOptions |
| `SimApiAuthCenter` | 群组/Profile/内部应用/系统登录/安全验证等 12 个接口 + `VerifySign` |
| `SimApiAuthIam` | 注册权限 / 获取权限标识 / 校验权限（无权限抛 403） |
| `SimApiAuthCenterMiddleware` | 网关透传：`X-SimApi-Gate-Auth/Time/Sign` 三头 MD5 校验 → Base64 解码 LoginInfo |
```cangjie
@@ -491,12 +491,12 @@ options.configureSimApiDoc { doc =>
}
```
| 路由 | 说明 |
|------|------|
| `/{prefix}/all.html` | 多文档切换页（顶部栏下拉选择所有文档） |
| 路由 | 说明 |
| --------------------- | ------------------------------------------ |
| `/{prefix}/all.html` | 多文档切换页（顶部栏下拉选择所有文档） |
| `/{prefix}/{id}.html` | 单文档页（无顶部栏，自动加载 `{id}.json`） |
| `/{prefix}/urls` | 文档列表 JSON（供 Swagger UI 下拉） |
| `/{prefix}/{id}.json` | OpenAPI 文档 JSON |
| `/{prefix}/urls` | 文档列表 JSON（供 Swagger UI 下拉） |
| `/{prefix}/{id}.json` | OpenAPI 文档 JSON |
> Swagger UI 静态资源（CSS/JS/HTML）以 Base64 内联编译，运行时由 `OpenApiUIMiddleware` 解码输出。资源更新后运行 `pwsh tools/gen-swagger-ui-resources.ps1` 重新生成。
@@ -504,13 +504,13 @@ options.configureSimApiDoc { doc =>
接口返回值自动封装为统一响应格式，**文档中 response schema 也体现封装**：
| 返回类型 | `@OriginResponse` | 文档 response schema |
|----------|-------------------|---------------------|
| `SimApiBaseResponse`/`SimApiResponse<T>`/`SimApiDataResponse` | - | 原样不封装 |
| 任意类型 | ✓ | 原样不封装 |
| `Unit` (void) | ✗ | `{code: int64, message: string}` |
| `String` | ✗ | `{code, message, data: {type: string}}` |
| DTO | ✗ | `{code, message, data: {$ref: DTO}}` |
| 返回类型 | `@OriginResponse` | 文档 response schema |
| ------------------------------------------------------------- | ----------------- | --------------------------------------- |
| `SimApiBaseResponse`/`SimApiResponse<T>`/`SimApiDataResponse` | - | 原样不封装 |
| 任意类型 | ✓ | 原样不封装 |
| `Unit` (void) | ✗ | `{code: int64, message: string}` |
| `String` | ✗ | `{code, message, data: {type: string}}` |
| DTO | ✗ | `{code, message, data: {$ref: DTO}}` |
### 认证锁图标
@@ -625,11 +625,11 @@ SimApiExtensions.addSimApi(builder) { options =>
simapi 提供 Spire MVC 控制器（继承 `SimApiBaseController`），`addSimApi` 自动注册内置控制器 + 自动扫描调用者包中的控制器：
| 控制器 | 路由 | 说明 |
|--------|------|------|
| `SimApiCommonController` | `/exception/{code}`、`/config`、`/user/info` | 通用内置路由 |
| `SimApiAuthController` | `/auth/logout` | 退出登录 |
| `SimApiBaseController` | — | 基类：`loginInfo` / `loginToken`（访问时自动校验登录，未登录抛 401） |
| 控制器 | 路由 | 说明 |
| ------------------------ | -------------------------------------------- | -------------------------------------------------------------------- |
| `SimApiCommonController` | `/exception/{code}`、`/config`、`/user/info` | 通用内置路由 |
| `SimApiAuthController` | `/auth/logout` | 退出登录 |
| `SimApiBaseController` | — | 基类：`loginInfo` / `loginToken`（访问时自动校验登录，未登录抛 401） |
```cangjie
import simcu::simapi.controllers.*
@@ -656,10 +656,10 @@ public class MyController <: SimApiBaseController {
以下原包功能因仓颉生态暂无对应库（Hangfire/MQTT），**选项保留但未实现**：
| 选项 | 原功能 | 状态 |
|------|--------|------|
| `enableSynapse` | MQTT 通信 | ❌ 未实现 |
| `enableJob` | Hangfire 任务调度 | ❌ 未实现 |
| 选项 | 原功能 | 状态 |
| --------------- | ----------------- | -------- |
| `enableSynapse` | MQTT 通信 | ❌ 未实现 |
| `enableJob` | Hangfire 任务调度 | ❌ 未实现 |
> ✅ 已实现（曾为占位）：`enableSimApiDoc`（OpenAPI 文档 + Swagger UI）、`enableSimApiStorage`（S3/MinIO，自实现 AWS SigV4）、`enableSimApiAuthGate`（AuthSDK 认证中心）、`SimApiAesUtil`（纯仓颉 AES-256-CBC）、`SimApiAuthChecker`、`@SimApiSign` / `@AesBody` 声明式注解、内置路由自定义路径。
@@ -667,16 +667,16 @@ public class MyController <: SimApiBaseController {
## 依赖
| 依赖 | 用途 |
|------|------|
| `soulsoft_web_http / routing / hosting` | Web 框架 |
| `soulsoft_extensions_logging` 系列 | 日志 |
| `soulsoft_extensions_injection` | 依赖注入 |
| `soulsoft_extensions_configuration` | 配置 |
| `simcu::serialization`（path 依赖） | JSON 序列化（simapi 自研，反射免标注） |
| `redis`（pkg.cangjie-lang.cn） | Redis 客户端（认证/缓存 Redis 模式） |
| `stdx`（CANGJIE_STDX_PATH） | 标准扩展库（md5/sha1/base64/http/tls） |
| `soulsoft_web_mvc` | MVC 框架（控制器路由、模型绑定） |
| 依赖 | 用途 |
| --------------------------------------- | -------------------------------------- |
| `soulsoft_web_http / routing / hosting` | Web 框架 |
| `soulsoft_extensions_logging` 系列 | 日志 |
| `soulsoft_extensions_injection` | 依赖注入 |
| `soulsoft_extensions_configuration` | 配置 |
| `simcu::serialization`（path 依赖） | JSON 序列化（simapi 自研，反射免标注） |
| `redis`（pkg.cangjie-lang.cn） | Redis 客户端（认证/缓存 Redis 模式） |
| `stdx`（CANGJIE_STDX_PATH） | 标准扩展库（md5/sha1/base64/http/tls） |
| `soulsoft_web_mvc` | MVC 框架（控制器路由、模型绑定） |
> 构建前需设置 `CANGJIE_STDX_PATH` 指向本地 stdx 的 `static/stdx` 目录。
> OpenAPI Swagger UI 静态资源内置（Base64 内联），更新资源后运行 `pwsh tools/gen-swagger-ui-resources.ps1`。