GraphQL × TypeScript × Zod：Code Generator を活用した型安全な API 開発とスキーマ管理

npm install --save-dev @graphql-codegen/cli

npm install --save-dev @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo

type Author {
  id: Int!
  firstName: String!
  lastName: String!
  posts(findTitle: String): [Post]
}
 
type Post {
  id: Int!
  title: String!
  author: Author
}
 
type Query {
  posts: [Post]
}

import { request, gql } from 'graphql-request'
import { useQuery } from '@tanstack/react-query'
 
interface PostsQuery {
  posts: {
    id: string
    title: string
    author?: {
      id: string
      firstName: string
      lastName: string
    }
  }[]
}
 
const postsQueryDocument = gql`
  query Posts {
    posts {
      id
      title
      author {
        id
        firstName
        lastName
      }
    }
  }
`
 
const Posts = () => {
  const { data } = useQuery<PostsQuery>('posts', async () => {
    const { posts } = await request(endpoint, postsQueryDocument)
    return posts
  })
 
}

interface PostsQuery {
  posts: {
    id: string
    title: string
    author?: {
      id: string
      firstName: string
      lastName: string
    }
  }[]
}

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
   schema: 'https://localhost:4000/graphql',
   documents: ['src/**/*.tsx'],
   generates: {
      './src/gql/': {
        preset: 'client',
      }
   }
}
export default config

npx graphql-codegen

import { request } from 'graphql-request'
import { useQuery } from '@tanstack/react-query'
import { graphql } from './gql/gql'
 
const postsQueryDocument = graphql(/* GraphQL */ `
  query Posts {
    posts {
      id
      title
      author {
        id
        firstName
        lastName
      }
    }
  }
`)
 
const Posts = () => {
  const { data } = useQuery<PostsQuery>('posts', async () => {
    const { posts } = await request(endpoint, postsQueryDocument)
    return posts
  })
}

type Author {
  id: Int!
  firstName: String!
  lastName: String!
}
 
type Post {
  id: Int!
  title: String!
  author: Author
}
 
type Query {
  posts: [Post] # 単一の投稿を取得する
  post(id: ID!): Post # 単一の投稿を取得する
}

// ダミーデータ
const posts = [
  { id: 1, title: "GraphQL Introduction", authorId: 1 },
  { id: 2, title: "Advanced GraphQL", authorId: 1 },
  { id: 3, title: "GraphQL with Apollo", authorId: 2 },
];

export const resolvers = {
  Query: {
    // すべての投稿を取得
    posts: () => posts,

    // IDで特定の投稿を取得
    post: (_parent: any, args: { id: number }) =>
      posts.find((post) => post.id === args.id),
  },
};

import { readFileSync } from "fs";
import { gql } from "graphql-tag";
import path from "path";

const schemaPath = path.resolve(process.cwd(), "../packages/graphql/schema/post.graphql");

const typeDefs = gql(readFileSync(schemaPath, "utf-8"));

export { typeDefs };

import express from "express";
import cors from "cors";
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { resolvers } from './graphql/resolvers';
import { typeDefs } from "./graphql/type";

const server = new ApolloServer({ typeDefs, resolvers });

const app = express();
const PORT = process.env.PORT || 4000;

const startServer = async () => {
  await server.start();

  app.use(
    '/graphql',
    cors(),
    express.json(),
    expressMiddleware(server)
  );

  app.listen(PORT, () => {
    console.log('GraphQL server is running at http://localhost:4000/graphql');
  });
};

startServer();

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: '../packages/graphql/schema/**/*.graphql',
  generates: {
    "generated/graphql.ts": {
      plugins: [
        'typescript',
        'typescript-operations',
      ],
    },
  } 
};
export default config;

export type Maybe<T> = T | null;
export type InputMaybe<T> = Maybe<T>;
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };
export type MakeEmpty<T extends { [key: string]: unknown }, K extends keyof T> = { [_ in K]?: never };
export type Incremental<T> = T | { [P in keyof T]?: P extends ' $fragmentName' | '__typename' ? T[P] : never };
/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: { input: string; output: string; }
  String: { input: string; output: string; }
  Boolean: { input: boolean; output: boolean; }
  Int: { input: number; output: number; }
  Float: { input: number; output: number; }
};

export type Author = {
  __typename?: 'Author';
  firstName: Scalars['String']['output'];
  id: Scalars['Int']['output'];
  lastName: Scalars['String']['output'];
  posts?: Maybe<Array<Maybe<Post>>>;
};


export type AuthorPostsArgs = {
  findTitle?: InputMaybe<Scalars['String']['input']>;
};

export type Post = {
  __typename?: 'Post';
  author?: Maybe<Author>;
  id: Scalars['Int']['output'];
  title: Scalars['String']['output'];
};

export type Query = {
  __typename?: 'Query';
  post?: Maybe<Post>;
  posts?: Maybe<Array<Maybe<Post>>>;
};


export type QueryPostArgs = {
  id: Scalars['ID']['input'];
};

query GetPosts {
  posts {
    id
    title
    author {
      firstName
      lastName
    }
  }
}

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: '../packages/graphql/schema/**/*.graphql',
  documents: '../packages/graphql/operations/**/*.graphql',
  generates: {
    "generated/graphql.ts": {
      plugins: [
        'typescript',
        'typescript-operations',
        'typescript-graphql-request',
      ],
    },
  } 
};
export default config;

export type GetPostsQuery = { 
  __typename?: 'Query', 
  posts?: Array<{
     __typename?: 'Post', 
     id: number, 
     title: string, 
     author?: { 
      __typename?: 'Author', 
      firstName: string, 
      lastName: string 
    } | null 
  } | null> | null 
};

export const GetPostsDocument = gql`
    query GetPosts {
  posts {
    id
    title
    author {
      firstName
      lastName
    }
  }
}
    `;

export type SdkFunctionWrapper = <T>(action: (requestHeaders?:Record<string, string>) => Promise<T>, operationName: string, operationType?: string, variables?: any) => Promise<T>;


const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationType, _variables) => action();

export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
  return {
    GetPosts(variables?: GetPostsQueryVariables, requestHeaders?: GraphQLClientRequestHeaders): Promise<GetPostsQuery> {
      return withWrapper((wrappedRequestHeaders) => client.request<GetPostsQuery>(GetPostsDocument, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'GetPosts', 'query', variables);
    }
  };
}
export type Sdk = ReturnType<typeof getSdk>;

import { GraphQLClient } from "graphql-request";
import { getSdk } from "../generated/graphql"; 

const client = new GraphQLClient("http://localhost:4000/graphql");
const sdk = getSdk(client);

export async function getPost() {
  const response = await sdk.GetPosts();
  return response.posts
}

import { useEffect, useState } from "react";
import { GetPostsQuery } from "../generated/graphql";
import { getPosts } from "./service";

function App() {
  const [posts, setPosts] = useState<GetPostsQuery["posts"] | null>(null);

  useEffect(() => {
    getPosts()
      .then((data) => {
        setPosts(data);
      })
      .catch((error) => {
        console.error(error);
      });
  }, []);

  return (
    <div>
      <h1>React + Express</h1>
      {posts === null || posts === undefined ? (
        <p>Loading...</p>
      ) : posts.length === 0 ? (
        <p>No posts found.</p>
      ) : (
        <ul>
          {posts.map((post) => (
            <li key={post?.id}>
              <h2>{post?.title}</h2>
              <p>Author: {post?.author?.firstName} {post?.author?.lastName}</p>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

export default App;

schema-change:
  - "apps/packages/graphql/schema/**/*.graphql"

name: "Add label for GraphQL schema changes"

on:
  pull_request:

permissions:
  pull-requests: write
  contents: read

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Apply labels
        uses: actions/labeler@v4
        with:
          repo-token: "${{ secrets.GITHUB_TOKEN }}"

type Post {
  id: Int!
  title: String!
  description: String @deprecated(reason: "Use 'excerpt' instead.")
  author: Author
}

import { z } from 'zod';

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

const validateResponse = (data: any) => {
  const result = userSchema.safeParse(data);
  if (!result.success) {
    console.error("Invalid response data:", result.error.format());
    throw new Error("Response validation failed");
  }
  return result.data;
};

import express from 'express';
import { z } from 'zod';

const app = express();

const responseSchema = z.object({
  success: z.boolean(),
  data: z.object({
    id: z.number(),
    name: z.string(),
  }),
});

app.get('/user', (req, res) => {
  const responseData = {
    success: true,
    data: { id: 1, name: "Taro" },
  };

  const validationResult = responseSchema.safeParse(responseData);
  if (!validationResult.success) {
    return res.status(500).json({ error: "Invalid response format" });
  }

  res.json(responseData);
});

app.listen(3000, () => console.log("Server running on port 3000"));

interface User {
  id: number;
  name: string;
  email: string;
}

async function fetchUser(): Promise<User> {
  const response = await fetch("https://api.example.com/user");
  const data = await response.json();
  return data; // 型チェックを強化するためにバリデーションを追加
}

async function fetchUser(): Promise<User> {
  const response = await fetch("https://api.example.com/user");
  const data = await response.json();
  return data as User; // ⚠️ 型アサーションのみだと不正なデータが入りうる
}

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

async function fetchUser(): Promise<User> {
  const response = await fetch("https://api.example.com/user");
  const data = await response.json();
  return UserSchema.parse(data); // ここで型チェックを実施
}

function isUser(data: unknown): data is User {
  return (
    typeof data === "object" && data !== null &&
    "id" in data && typeof (data as any).id === "number" &&
    "name" in data && typeof (data as any).name === "string" &&
    "email" in data && typeof (data as any).email === "string"
  );
}

async function fetchUser(): Promise<User> {
  const response = await fetch("https://api.example.com/user");
  const data = await response.json();
  if (!isUser(data)) {
    throw new Error("Invalid API response");
  }
  return data;
}

import { gql } from "graphql-tag";
import { request } from "graphql-request";
import { UserQuery } from "@generated/graphql";

const GET_USER = gql`
  query getUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

async function fetchUser(id: string): Promise<UserQuery> {
  const response = await request("/graphql", GET_USER, { id });
  return response;
}

import { ApolloServer, gql } from 'apollo-server';

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

npm install swagger-jsdoc swagger-ui-express

import express from 'express';
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const app = express();

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Sample API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};

const swaggerDocs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(3000, () => console.log('Server running on port 3000'));

const jsonServer = require('json-server');
const server = jsonServer.create();  // JSON Server のインスタンスを作成
const router = jsonServer.router('db.json');  // db.json をもとにルーティングを生成
const middlewares = jsonServer.defaults();  // JSON Server のデフォルトミドルウェア（CORS, ロギング, JSON パースなど）を適用

server.use(middlewares);  // ミドルウェア適用
server.use((req, res, next) => {
  console.log('Request received:', req.method, req.url);  // リクエストログを出力
  next();  // 次のミドルウェアへ処理を渡す
});
server.use(router);  // ルーターを適用

server.listen(3001, () => {
  console.log('JSON Server is running on port 3001');
});

server.use('/users', (req, res, next) => {
  req.query.limit = 10;  // クエリパラメータを強制的に追加
  next();
});

router.render = (req, res) => {
  res.json({
    success: true,
    data: res.locals.data
  });
};

npm install @graphql-tools/mock @graphql-tools/schema graphql-tag

import { makeExecutableSchema } from '@graphql-tools/schema';
import { addMocksToSchema } from '@graphql-tools/mock';
import { graphql } from 'graphql';

const typeDefs = `
  type User {
    id: ID!
    name: String!
  }
  type Query {
    users: [User]
  }
`;

const schema = makeExecutableSchema({ typeDefs });
const mockedSchema = addMocksToSchema({ schema });

graphql(mockedSchema, '{ users { id name } }').then((result) =>
  console.log(JSON.stringify(result, null, 2))
);