CJoy快速上手与示例解析

【免费下载链接】cjoy 一个高性能、可扩展、轻量、省心的仓颉Web框架。Rest， 宏路由，Json， 中间件，参数绑定与校验，文件上传下载，MCP...... 项目地址: https://gitcode.com/Cangjie-SIG/cjoy

CJoy是一个高性能、轻量级的仓颉Web框架，本文详细介绍了其依赖配置、快速启动、API使用及常见问题解决方案。从环境搭建到示例运行，帮助开发者快速掌握核心功能。

项目依赖与配置要求

CJoy 是一个高性能、轻量级的仓颉 Web 框架，其运行和开发需要满足一定的依赖和配置要求。以下是详细的依赖说明和配置指南。

依赖要求

1. 仓颉语言环境
   CJoy 基于仓颉语言开发，因此需要安装仓颉语言的 SDK 和运行时环境。以下是具体要求：

   • 仓颉版本：v1.0.0
     确保您的仓颉 SDK 版本与项目要求一致，否则可能会出现兼容性问题。

   • stdx 包
     CJoy 依赖仓颉的 stdx 包，需要从 仓颉编程语言 stdx 下载对应版本，并解压到指定目录。

2. 操作系统支持
   CJoy 支持以下操作系统：

   • Linux（推荐）
   • MacOS
   • Windows（需通过 WSL 运行）

3. 目录结构要求
   为了正确加载依赖，需要将 stdx 包解压到与仓颉 SDK 并列的目录 cangjiestdx 下，结构如下：

   cangjie/          # 仓颉 SDK 目录
   cangjiestdx/      # 新建目录
     linux_x86_64_llvm/  # 解压 stdx 包，不同操作系统目录名称不同
   

   如果 stdx 包未按上述目录配置，需修改 cjpm.toml 文件中的 [target.xx.bin-dependencies] 部分的 path-option。

配置要求

1. cjpm.toml 配置
   CJoy 使用 cjpm 作为包管理工具，项目的依赖和配置信息存储在 cjpm.toml 文件中。以下是关键配置项：

   [dependencies]
   cjoy = { git = "https://gitcode.com/Cangjie-SIG/cjoy.git", branch = "main" }
   
   [target.linux_x86_64_llvm.bin-dependencies]
   path-option = ["cangjiestdx/linux_x86_64_llvm"]
   

2. TLS 配置
   如果项目需要使用 HTTPS 或 HTTP2，需提供证书和私钥文件的路径。示例：

   let certificatePath = "src/examples/tls/server_cert.pem"
   let certificateKeyPath = "src/examples/tls/server_key.pem"
   joy.run("127.0.0.1", 18881, certificatePath, certificateKeyPath, h2: true)
   

3. 多线程支持
   CJoy 支持多线程运行，可以通过 spawn 启动异步服务：

   let joy = Joy.default()
   spawn { =>
       joy.run("127.0.0.1", 18881)
   }
   

运行示例

1. 克隆项目

   git clone https://gitcode.com/Cangjie-SIG/cjoy.git
   

2. 运行示例
   使用 cjpm 运行示例：

   cjpm run --name cjoy.examples.tls
   

3. 测试与构建

   cjpm test
   cjpm build
   

总结

CJoy 的依赖和配置要求主要集中在仓颉语言环境和 stdx 包的配置上。通过合理的目录结构和 cjpm.toml 配置，可以轻松满足项目的运行需求。此外，TLS 和多线程的支持为项目提供了更高的灵活性和安全性。

快速启动与示例运行

CJoy 提供了丰富的示例代码，帮助开发者快速上手并理解框架的核心功能。以下是如何快速启动服务并运行示例的详细指南。

安装依赖

在运行示例之前，需要确保项目依赖已正确安装。执行以下命令安装依赖：

cjpm install

如果未安装 cjpm，请参考项目文档配置仓颉环境。

示例代码结构

CJoy 的示例代码位于 src/examples 目录下，涵盖了多种功能场景：

• 文件服务 (fileserver/main.cj)
• REST API (rest/main.cj)
• WebSocket (websocket/main.cj)
• TLS 加密通信 (tls/main.cj)
• MCP 服务 (mcpserver/main.cj 和 mcpclient/main.cj)

每个示例目录中均包含一个 main.cj 文件，作为入口点。

运行示例

通过以下命令运行指定示例：

cjpm run --name cjoy.examples.<示例名称>

例如，运行文件服务示例：

cjpm run --name cjoy.examples.fileserver

示例：文件服务

以下是一个简单的文件服务示例代码：

import cjoy.*
import cjoy.fs.*

main(): Int64 {
    let joy = Joy.default()
    joy.router.serveFiles("/static", "src/examples/fileserver/static")
    joy.run("127.0.0.1", 18881)
    return 0
}

启动后，访问 http://127.0.0.1:18881/static 即可查看静态文件。

示例：REST API

以下是一个简单的 REST API 示例：

import cjoy.*
import cjoy.json.*

@Json
class User {
    var id: String = ""
    var name: String = ""
}

main(): Int64 {
    let joy = Joy.default()
    joy.router.get("/users/{id}", {ctx: JoyContext =>
        let user = User()
        user.id = ctx.getParam("id") ?? "0"
        user.name = "Alice"
        ctx.json(200, user)
    })
    joy.run("127.0.0.1", 18881)
    return 0
}

启动后，访问 http://127.0.0.1:18881/users/1 将返回 JSON 格式的用户信息。

调试与日志

CJoy 默认开启调试日志，可以通过以下配置关闭：

let cfg = JoyConfig(enableDebugLog: false)
let joy = Joy.create(cfg)

日志将输出到控制台，便于开发者调试。

总结

通过运行示例代码，开发者可以快速掌握 CJoy 的核心功能，包括路由、文件服务、REST API 和 WebSocket 等。更多示例请参考 src/examples 目录。

API使用与宏开发

CJoy框架通过宏和API提供了强大的功能，简化了Web开发中的常见任务。以下将详细介绍API的使用和宏的开发，帮助开发者快速上手并充分利用框架的能力。

参数绑定

CJoy支持通过宏将Query、PostForm、Header等参数绑定到对象上，简化参数处理流程。

示例代码

import cjoy.bind.*

@Bind
public struct BindParam {
    let str: String
    var str2: ?String = None
    var i64: Int64 = 0
    @BindField[name = int]
    var i2_64: Int = 0
    var i3_64: ?Int = None
    var arr: Array<String> = []
    var list: ArrayList<String> = ArrayList<String>()
}

router.get("/bind", {ctx: JoyContext =>
    let params = ctx.bindQuery<BindParam>()
    ctx.string("bind")
})

宏说明

宏	属性参数	说明
@Bind	-	作用于类或结构体，支持参数绑定映射。
@BindField	name, default, timeformat	作用于成员变量，指定绑定字段名称、默认值和时间格式。

支持的字段类型

• String, ?String
• 基本类型及其可空版本
• Array<String>, ArrayList<String>
• DateTime, ?DateTime

---

路由宏

CJoy提供了一系列宏来简化路由注册和参数处理。

Handler宏

宏	属性参数	说明
@Get	path, produce	注册GET请求处理函数。
@Post	path, produce	注册POST请求处理函数。
@Handler	path, produce, methods	通过methods指定支持的HTTP方法。

参数展开宏

宏	说明
@PathParam	获取路由参数。
@QueryParam	获取URL查询参数。
@BodyParam	获取请求体参数。
@QueryBindParam	将多个查询参数绑定到对象。

示例代码

@Get[path = "/users/{id}", produce = "json"]
func getUser(@PathParam id: String): UserInfo {
    UserInfo(id: id, name: "test")
}

---

Middleware宏

通过宏可以轻松注册中间件，实现请求拦截和处理。

示例代码

@Middleware[groups = "/api"]
func authMiddleware(ctx: JoyContext, chain: JoyRequestHandlerChain): Unit {
    if (!ctx.isAuthenticated()) {
        ctx.status(401).string("Unauthorized")
    } else {
        chain.next(ctx)
    }
}

宏说明

宏	属性参数	说明
@Middleware	groups	指定中间件生效的路由组。

---

注册与启动

所有通过宏生成的Handler和Middleware需要显式注册到服务实例中。

示例代码

let joy = Joy.default()
JoyMiddlewares.registerTo(joy)
JoyHandlers.registerTo(joy)
joy.run("127.0.0.1", 18881)

注意事项

1. Middleware需先于Handler注册。
2. 确保在服务启动前完成所有注册操作。

通过以上内容，开发者可以快速掌握CJoy框架的API和宏开发能力，提升开发效率。

常见问题与解决方案

在使用CJoy框架时，开发者可能会遇到一些常见问题。以下是一些典型问题及其解决方案，帮助您快速定位并解决问题。

1. CORS跨域问题

问题描述
在开发过程中，前端请求可能会因跨域问题被拦截，导致请求失败。

解决方案
CJoy提供了内置的CORS中间件，可以通过以下方式启用：

import cjoy.middleware.*

main(): Int64 {
    let joy = Joy.default()
    joy.use(CORSMiddleware(
        allowOrigins: ["http://localhost:3000"],
        allowMethods: ["GET", "POST"],
        allowHeaders: ["Content-Type"]
    ))
    joy.run("127.0.0.1", 18881)
    return 0
}

常见错误日志

• [CORS] Preflight aborted, origin '${origin}' not allowed
• [CORS] Preflight aborted, method '${method}' not allowed
• [CORS] Preflight aborted, headers '${header}' not allowed

解决步骤

1. 确保allowOrigins中包含了前端请求的域名。
2. 检查allowMethods和allowHeaders是否覆盖了前端请求所需的类型。

---

2. 请求参数校验失败

问题描述
使用@Valid或@Validated宏校验请求参数时，可能会因参数不符合规则而抛出异常。

解决方案
CJoy的校验宏支持自定义错误提示，例如：

@Valid
class User {
    @Size(min = 3, max = 20, msg = "用户名长度必须在3到20之间")
    var name: String = ""
}

常见错误日志

• the verification error tip

解决步骤

1. 检查校验规则是否合理（如@Size、@NotNull等）。
2. 确保错误提示信息清晰易懂。

---

3. JSON序列化/反序列化问题

问题描述
在绑定JSON请求或返回JSON响应时，可能会因字段类型不匹配或缺失导致错误。

解决方案
使用@Json宏标记类，并确保字段类型正确：

@Json
class User {
    var id: String = ""
    var name: String = ""
}

常见错误日志

• JSONRPCResponse(id: "server-error", error: ex.error)

解决步骤

1. 检查类是否标记为@Json。
2. 确保字段类型与JSON数据匹配。

---

4. MCP服务调用失败

问题描述
在调用MCP服务时，可能会因方法未找到或参数错误导致失败。

解决方案
检查MCP服务的工具、资源或提示是否正确定义和注册：

@ToolFuncs
func myTool(@ToolParam name: String): String {
    return "Hello, ${name}!"
}

常见错误日志

• [MCP] not found tool handler, name=${req.name}
• [MCP] call tool failed, ${ex.message}

解决步骤

1. 确保工具方法标记为@ToolFuncs。
2. 检查参数是否与MCP请求匹配。

---

5. 文件上传/下载问题

问题描述
在处理文件上传或下载时，可能会因路径或权限问题导致失败。

解决方案
使用内置的FileServer中间件简化文件操作：

joy.router.static("/files", "/path/to/files")

常见错误日志

• [FileServer] not found file, path=${path}

解决步骤

1. 确保文件路径正确。
2. 检查服务器是否有权限访问文件。

---

通过以上解决方案，您可以快速定位并解决CJoy框架中的常见问题。如果问题仍未解决，建议查阅项目文档或提交Issue。

总结

CJoy框架通过清晰的依赖管理、丰富的示例代码和强大的宏功能，为仓颉语言开发者提供了高效的Web开发体验。从基础配置到高级功能，本文涵盖了关键知识点，助力开发者快速上手并解决常见问题。

【免费下载链接】cjoy 一个高性能、可扩展、轻量、省心的仓颉Web框架。Rest， 宏路由，Json， 中间件，参数绑定与校验，文件上传下载，MCP...... 项目地址: https://gitcode.com/Cangjie-SIG/cjoy