Pylon

使用 Pylon 构建 GraphQL API 既简单又直接。Pylon 是一个构建于 Hono 之上的后端框架，并提供代码优先的 GraphQL API 开发方式。

GraphQL schema 从你的 TypeScript 定义中实时生成，使你能够专注于编写你的服务逻辑。这种方法显著提高了开发速度，增强了类型安全性，并减少了错误。

代码中的任何破坏性更改都会立即反映在你的 API 中，使你能够立即看到更改如何影响其功能。

查看 Pylon 以获取更多信息。

设置新的 Pylon 服务

Pylon 允许你使用 npm create pylon 命令创建一个新的服务。此命令会创建一个新的 Pylon 项目，其中包含基本的项目结构和配置。在设置过程中，你可以选择你偏好的运行时，例如 Bun、Node.js 或 Cloudflare Workers。

本指南使用 Bun 运行时。

创建新项目

要创建一个新的 Pylon 项目，请运行以下命令：

bash

npm create pylon my-pylon@latest

这将创建一个名为 my-pylon 的新目录，其中包含基本的 Pylon 项目结构。

项目结构

Pylon 项目的结构如下：

my-pylon/
├── .pylon/
├── src/
│   ├── index.ts
├── package.json
├── tsconfig.json

.pylon/: 包含你项目的生产构建。
src/: 包含你项目的源代码。
src/index.ts: 你的 Pylon 服务的入口点。
package.json: npm 包配置文件。
tsconfig.json: TypeScript 配置文件。

基础示例

这是一个基础 Pylon 服务的示例：

import { app } from '@getcronit/pylon'

export const graphql = {
  Query: {
    sum: (a: number, b: number) => a + b,
  },
  Mutation: {
    divide: (a: number, b: number) => a / b,
  },
}

export default app

保护 API 安全

Pylon 与云原生身份和访问管理解决方案 ZITADEL 集成，为你的 API 提供安全的身份验证和授权。你可以按照 ZITADEL 文档中概述的步骤轻松保护你的 Pylon API。

创建更复杂的 API

Pylon 允许你利用其实时 schema 生成能力来创建更复杂的 API。有关受支持的 TypeScript 类型以及如何定义你的 API 的更多信息，请参阅 Pylon 文档

此示例演示了如何在 Pylon 中定义复杂类型和服务。通过利用 TypeScript 类和方法，你可以创建强大的 API，这些 API 可以与数据库、外部服务和其他资源进行交互。

import { app } from '@getcronit/pylon'

class Post {
  id: string
  title: string

  constructor(id: string, title: string) {
    this.id = id
    this.title = title
  }
}

class User {
  id: string
  name: string

  constructor(id: string, name: string) {
    this.id = id
    this.name = name
  }

  static async getById(id: string): Promise<User> {
    // 从数据库获取用户数据
    return new User(id, 'John Doe')
  }

  async posts(): Promise<Post[]> {
    // 从数据库获取此用户的帖子
    return [new Post('1', 'Hello, world!')]
  }

  async $createPost(title: string, content: string): Promise<Post> {
    // 为此用户在数据库中创建一个新帖子
    return new Post('2', title)
  }
}

export const graphql = {
  Query: {
    user: User.getById,
  },
  Mutation: {
    createPost: (userId: string, title: string, content: string) => {
      const user = User.getById(userId)
      return user.$createPost(title, content)
    },
  },
}

export default app

调用 API

可以使用任何 GraphQL 客户端库调用 Pylon API。为了开发目的，建议使用 Pylon Playground，这是一个基于 Web 的 GraphQL IDE，允许你实时与你的 API 交互。

通过在你的项目目录中运行 bun run dev 来启动 Pylon 服务器。
通过在浏览器中导航到 http://localhost:3000/graphql 来打开 Pylon Playground。
在左侧面板中编写你的 GraphQL query 或 mutation。

Pylon Playground

获取对 Hono context 的访问权限

你可以通过使用 getContext 函数在代码中的任何位置访问 Hono context。此函数返回当前的 context 对象，其中包含有关请求、响应和其他特定于 context 的数据的信息。

import { app, getContext } from '@getcronit/pylon'

export const graphql = {
  Query: {
    hello: () => {
      const context = getContext()
      return `Hello, ${context.req.headers.get('user-agent')}`
    },
  },
}

export default app

有关 Hono context 对象及其属性的更多信息，请参阅 Hono 文档和 Pylon 文档。

Hono 在哪里发挥作用？

Pylon 构建于 Hono 之上，Hono 是一个轻量级的 Web 框架，用于构建 Web 应用程序和 API。 Hono 提供了处理 HTTP 请求和响应的核心功能，而 Pylon 扩展了此功能以支持 GraphQL API 开发。

除了 GraphQL 之外，Pylon 还允许你访问底层的 Hono app 实例，以添加自定义路由和中间件。这使你可以构建更复杂的 API 和服务，从而利用 Hono 的全部功能。

import { app } from '@getcronit/pylon'

export const graphql = {
  Query: {
    sum: (a: number, b: number) => a + b,
  },
  Mutation: {
    divide: (a: number, b: number) => a / b,
  },
}

// 向 Pylon app 添加自定义路由
app.get('/hello', (ctx, next) => {
  return new Response('Hello, world!')
})

结论

Pylon 是一个强大的 Web 框架，可以简化 GraphQL API 的开发。通过利用 TypeScript 类型定义，Pylon 提供了实时的 schema 生成，增强了类型安全性并减少了错误。借助 Pylon，你可以快速构建安全且可扩展的 API，以满足你的业务需求。 Pylon 与 Hono 的集成使你可以在专注于 GraphQL API 开发的同时使用 Hono 的所有功能。

有关 Pylon 的更多信息，请查看官方文档。

Pylon ​

设置新的 Pylon 服务 ​

创建新项目 ​

项目结构 ​

基础示例 ​

保护 API 安全 ​

创建更复杂的 API ​

调用 API ​

获取对 Hono context 的访问权限 ​

Hono 在哪里发挥作用？ ​

结论 ​

参见 ​