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`。
cjpm.lock
+11 -11
View File
@@ -4,17 +4,17 @@ version = 0
soulsoft_extensions_hosting = {version = "1.0.20260528"}
soulsoft_extensions_options_configuration = {version = "1.0.20260528"}
soulsoft_extensions_logging_console = {version = "1.0.20260528"}
redis = {version = "1.0.20260627"}
soulsoft_extensions_logging_configuration = {version = "1.0.20260528"}
soulsoft_identity_claims = {version = "1.0.20260528"}
soulsoft_web_http = {version = "1.0.20260528"}
"simcu::serialization" = {version = "1.2.1"}
soulsoft_extensions_configuration = {version = "1.0.20260528"}
soulsoft_web_routing = {version = "1.0.20260528"}
soulsoft_web_cors = {version = "1.0.20260528"}
soulsoft_extensions_injection = {version = "1.0.20260528"}
soulsoft_web_mvc = {version = "1.0.20260528"}
soulsoft_extensions_logging = {version = "1.0.20260528"}
soulsoft_serialization = {version = "1.0.20260528"}
soulsoft_extensions_options = {version = "1.0.20260528"}
soulsoft_extensions_logging = {version = "1.0.20260528"}
soulsoft_web_routing = {version = "1.0.20260528"}
soulsoft_identity_claims = {version = "1.0.20260528"}
soulsoft_extensions_logging_configuration = {version = "1.0.20260528"}
soulsoft_web_http = {version = "1.0.20260528"}
soulsoft_extensions_configuration = {version = "1.0.20260528"}
soulsoft_web_cors = {version = "1.0.20260528"}
soulsoft_extensions_injection = {version = "1.0.20260528"}
soulsoft_web_hosting = {version = "1.0.20260528"}
soulsoft_web_mvc = {version = "1.0.20260528"}
redis = {version = "1.0.20260627"}
"simcu::serialization" = {version = "1.2.1"}
cjpm.toml
+1 -1
View File
@@ -3,7 +3,7 @@ cjc-version = "1.1.3"
name = "simapi"
organization = "simcu"
description = "SimApi 仓颉版：ASP.NET Core 风格 API 基础框架（统一响应/异常拦截/Token认证/缓存/工具集/HTTP客户端）"
version = "1.1.0"
version = "1.1.2"
target-dir = ""
output-type = "static"
override-compile-option = ""
src/controllers/simapi_common_controller.cj
+1 -1
View File
@@ -31,7 +31,7 @@ public class SimApiCommonController <: SimApiBaseController {
*/
@HttpGet["exception/{code}"]
@SimApiDoc[ignore: true]
public func exceptionHandler(@FromRoute[] code: Int64) { // cjlint-ignore !G.FUN.02 注解绑定参数误报
public func exceptionHandler(@FromRoute[] code: Int64): Unit { // cjlint-ignore !G.FUN.02 注解绑定参数误报
SimApiError.error(code: code)
}
src/openapi/OpenApiUIMiddleware.cj
+4 -1
View File
@@ -92,7 +92,10 @@ public class OpenApiUIMiddleware <: IMiddleware {
private func serveFromWebRoot(context: HttpContext, relativePath: String): Bool {
let openApiRoot = Path(_env.webRootPath).join(_wwwRootSubDir)
let path = openApiRoot.join(relativePath).normalize()
if (!exists(path) || !isPathWithinRoot(path)) {
if (!exists(path)) {
return false
}
if (!isPathWithinRoot(path)) {
return false
}
src/openapi/infrastructure/OpenApiConstants.cj
+3 -3
View File
@@ -7,7 +7,7 @@
package simcu::simapi.openapi.infrastructure
protected class OpenApiConstants {
public static let DefaultOpenApiName = "default"
public static let DefaultDocumentName = "v1"
public static let DefaultOpenApiRoute = "/openapi/{documentName}.json"
public static let DefaultOpenApiName: String = "default"
public static let DefaultDocumentName: String = "v1"
public static let DefaultOpenApiRoute: String = "/openapi/{documentName}.json"
}
src/openapi/models/OpenApiComponents.cj
+2 -2
View File
@@ -18,12 +18,12 @@ public class OpenApiComponents <: IOpenApiSerializable {
/**
* @brief 表示组件中的架构集合。
*/
public var schemas = HashMap<String, OpenApiSchema>()
public var schemas: HashMap<String, OpenApiSchema> = HashMap<String, OpenApiSchema>()
/**
* @brief 表示组件中的安全方案集合。
*/
public var securitySchemes = HashMap<String, OpenApiSecurityScheme>()
public var securitySchemes: HashMap<String, OpenApiSecurityScheme> = HashMap<String, OpenApiSecurityScheme>()
/**
* @brief 创建 OpenAPI 组件实例。
src/openapi/models/OpenApiDocument.cj
+3 -3
View File
@@ -34,15 +34,15 @@ public class OpenApiDocument <: IOpenApiSerializable {
/**
* @brief 表示标签集合。
*/
public var tags = ArrayList<OpenApiTag>()
public var tags: ArrayList<OpenApiTag> = ArrayList<OpenApiTag>()
/**
* @brief 表示服务器集合。
*/
public var servers = ArrayList<OpenApiServer>()
public var servers: ArrayList<OpenApiServer> = ArrayList<OpenApiServer>()
/**
* @brief 表示安全需求集合。
*/
public var securityRequirements = ArrayList<OpenApiSecurityRequirement>()
public var securityRequirements: ArrayList<OpenApiSecurityRequirement> = ArrayList<OpenApiSecurityRequirement>()
/**
* @brief 创建 OpenAPI 文档对象。
src/openapi/models/OpenApiOperation.cj
+5 -5
View File
@@ -30,15 +30,15 @@ public class OpenApiOperation <: IOpenApiSerializable {
/**
* @brief 表示操作响应集合。
*/
public var response = OpenApiResponses()
public var response: OpenApiResponses = OpenApiResponses()
/**
* @brief 表示操作标签集合。
*/
public var tags = ArrayList<OpenApiTag>()
public var tags: ArrayList<OpenApiTag> = ArrayList<OpenApiTag>()
/**
* @brief 表示操作服务器集合。
*/
public var servers = ArrayList<OpenApiServer>()
public var servers: ArrayList<OpenApiServer> = ArrayList<OpenApiServer>()
/**
* @brief 表示操作请求体。
*/
@@ -46,11 +46,11 @@ public class OpenApiOperation <: IOpenApiSerializable {
/**
* @brief 表示操作参数集合。
*/
public var parameters = ArrayList<OpenApiParameter>()
public var parameters: ArrayList<OpenApiParameter> = ArrayList<OpenApiParameter>()
/**
* @brief 表示操作安全需求集合。
*/
public var security = ArrayList<OpenApiSecurityRequirement>()
public var security: ArrayList<OpenApiSecurityRequirement> = ArrayList<OpenApiSecurityRequirement>()
/**
* @brief 创建 OpenAPI 操作对象。
src/openapi/models/OpenApiPathItem.cj
+3 -3
View File
@@ -34,15 +34,15 @@ public class OpenApiPathItem <: IOpenApiSerializable {
/**
* @brief 表示路径项服务器集合。
*/
public var servers = ArrayList<OpenApiServer>()
public var servers: ArrayList<OpenApiServer> = ArrayList<OpenApiServer>()
/**
* @brief 表示路径项参数集合。
*/
public var parameters = ArrayList<OpenApiParameter>()
public var parameters: ArrayList<OpenApiParameter> = ArrayList<OpenApiParameter>()
/**
* @brief 表示路径项操作集合。
*/
public var operations = HashMap<OperationType, OpenApiOperation>()
public var operations: HashMap<OperationType, OpenApiOperation> = HashMap<OperationType, OpenApiOperation>()
/**
* @brief 创建 OpenAPI 路径项对象。
src/openapi/models/OpenApiRequestBody.cj
+1 -1
View File
@@ -26,7 +26,7 @@ public class OpenApiRequestBody <: IOpenApiSerializable {
/**
* @brief 表示请求体内容映射。
*/
public var content = HashMap<String, OpenApiMediaType>()
public var content: HashMap<String, OpenApiMediaType> = HashMap<String, OpenApiMediaType>()
/**
* @brief 创建 OpenAPI 请求体对象。
src/openapi/models/OpenApiResponse.cj
+1 -1
View File
@@ -22,7 +22,7 @@ public class OpenApiResponse <: IOpenApiSerializable {
/**
* @brief 表示响应内容映射。
*/
public var content = HashMap<String, OpenApiMediaType>()
public var content: HashMap<String, OpenApiMediaType> = HashMap<String, OpenApiMediaType>()
/**
* @brief 创建 OpenAPI 响应对象。
src/openapi/models/OpenApiSchema.cj
+3 -3
View File
@@ -46,11 +46,11 @@ public class OpenApiSchema <: IOpenApiSerializable {
/**
* @brief 表示对象属性集合。
*/
public var properties = HashMap<String, OpenApiSchema>()
public var properties: HashMap<String, OpenApiSchema> = HashMap<String, OpenApiSchema>()
/**
* @brief 表示 allOf 组合架构。
*/
public var allOf = ArrayList<OpenApiSchema>()
public var allOf: ArrayList<OpenApiSchema> = ArrayList<OpenApiSchema>()
/**
* @brief 表示是否允许附加属性。
*/
@@ -70,7 +70,7 @@ public class OpenApiSchema <: IOpenApiSerializable {
* @param reference 架构引用。
* @param description 架构描述。
*/
public init(title!: ?String = None, nullable!: ?Bool = None, `type`!: ?String = None, items!: ?OpenApiSchema = None,
public init(title!: ?String = None, nullable!: ?Bool = None, `type`!: ?String = None, items!: ?OpenApiSchema = None, // cjlint-ignore !G.FUN.02
format!: ?String = None, reference!: ?OpenApiReference = None, description!: ?String = None) {
this.title = title
this.format = format
src/openapi/models/OpenApiSchemaTypes.cj
+3 -3
View File
@@ -13,9 +13,9 @@ private let numbers = ["Float16", "Float32", "Float64", "Decimal"]
private let integers = ["Int8", "Int16", "Int32", "Int64", "UInt8", "UInt16", "UInt32", "UInt64"]
protected class OpenApiSchemaTypes {
public static const OBJECT = "object"
public static const STRING = "string"
public static const ARRAY = "array"
public static const OBJECT: String = "object"
public static const STRING: String = "string"
public static const ARRAY: String = "array"
/**
* @brief 将类型信息转换为 OpenAPI Schema 类型名称。
src/openapi/services/OpenApiDocumentService.cj
+1 -1
View File
@@ -260,7 +260,7 @@ protected class OpenApiDocumentService {
/*
来自请求体的参数
*/
private func createOpenApiOperationRequestBody(endpoint: RouteEndpoint, actionDescriptor: ControllerActionDescriptor): ?OpenApiRequestBody {
private func createOpenApiOperationRequestBody(endpoint: RouteEndpoint, actionDescriptor: ControllerActionDescriptor): ?OpenApiRequestBody { // cjlint-ignore !G.FUN.02 endpoint 未使用
var requestBody = OpenApiRequestBody(required: true)
let parameters = HashMap<String, OpenApiSchema>()
for (parameter in actionDescriptor.actionFunction.parameters) {