REST から GraphQL へ:移行ガイド
この記事は原文から機械翻訳されています。
記事を読み込み中...
記事を読み込み中...
この記事は原文から機械翻訳されています。
Web アプリケーションの複雑さが増すにつれ、多くの組織が REST API から GraphQL への移行を検討しています。この包括的なガイドでは、移行プロセスを順を追って説明し、ベストプラクティスと避けるべき一般的な落とし穴を強調します。
まず、REST と GraphQL のアプローチの根本的な違いを比較しましょう:
| 機能 | REST | GraphQL |
| エンドポイント | 複数のエンドポイント | 単一のエンドポイント |
| データ取得 | 固定されたレスポンス構造 | 柔軟でクライアント指定可能 |
| バージョニング | 通常は必要 | 継続的な進化 |
| ネットワークリクエスト | 複数リクエストが一般的 | 単一リクエストで十分 |
典型的な REST API 構造の例:
// REST API Endpoints
GET /api/users/:id
GET /api/users/:id/posts
GET /api/posts
POST /api/posts
PUT /api/posts/:id
// Example REST Controller
class UserController {
async getUser(req, res) {
const user = await User.findById(req.params.id);
const posts = await Post.find({ userId: req.params.id });
res.json({ user, posts });
}
}
REST エンドポイントを GraphQL スキーマに変換します:
type User {
id: ID!
username: String!
email: String!
posts: [Post!]!
profile: Profile
}
type Post {
id: ID!
title: String!
content: String!
author: User!
comments: [Comment!]!
createdAt: DateTime!
}
type Profile {
bio: String
avatar: String
socialLinks: [SocialLink!]!
}
type Comment {
id: ID!
content: String!
author: User!
}
type Query {
user(id: ID!): User
users(limit: Int, offset: Int): [User!]!
post(id: ID!): Post
posts(
authorId: ID
limit: Int
offset: Int
sortBy: PostSortInput
): [Post!]!
}
type Mutation {
createPost(input: CreatePostInput!): Post!
updatePost(id: ID!, input: UpdatePostInput!): Post!
deletePost(id: ID!): Boolean!
}
バッチ処理のために DataLoader を使った効率的なリゾルバを作成します:
// DataLoader setup
const userLoader = new DataLoader(async (userIds) => {
const users = await User.find({ _id: { $in: userIds } });
return userIds.map(id => users.find(user => user.id === id));
});
// GraphQL resolvers
const resolvers = {
Query: {
user: async (_, { id }) => userLoader.load(id),
posts: async (_, { limit, offset, authorId }) => {
const query = authorId ? { authorId } : {};
return Post.find(query).skip(offset).limit(limit);
}
},
User: {
posts: async (parent) => {
return Post.find({ authorId: parent.id });
}
},
Post: {
author: async (parent) => userLoader.load(parent.authorId)
}
};
REST と GraphQL の両方のリクエストを処理するゲートウェイを作成します:
// API Gateway setup
const gateway = express();
// REST endpoints
gateway.use('/api', restRouter);
// GraphQL endpoint
gateway.use('/graphql',
graphqlHTTP({
schema,
graphiql: true,
context: ({ req }) => ({
auth: req.headers.authorization,
loaders: {
user: userLoader,
post: postLoader
}
})
})
);
次のコードは、ミドルウェアを使用して GraphQL API に認証を実装する方法を示しています。リクエストコンテキスト内の認証トークンの存在を確認し、トークンを検証し、リゾルバで使用できるようにユーザー情報をコンテキストに添付します。このパターンにより、保護されたミューテーションとクエリへの安全なアクセスが保証されます:
// GraphQL Authentication middleware
const authenticate = async (resolve, root, args, context, info) => {
if (!context.auth) {
throw new Error('Authentication required');
}
const token = context.auth.split('Bearer ')[1];
const user = await verifyToken(token);
context.user = user;
return resolve(root, args, context, info);
};
// Apply to resolvers
const protectedResolvers = {
Mutation: {
createPost: authenticate(async (_, { input }, context) => {
return Post.create({
...input,
authorId: context.user.id
});
})
}
};
クライアントに明確なフィードバックを提供するために、GraphQL API に包括的なエラーハンドリングを実装します。以下は、カスタムエラーフォーマットと構造化されたエラーレスポンスを含むエラーハンドリング実装の例です:
// Custom error handling
const formatError = (error) => {
console.error(error);
return {
message: error.message,
code: error.extensions?.code || 'INTERNAL_SERVER_ERROR',
locations: error.locations,
path: error.path,
};
};
// Implementation in schema
const typeDefs = gql`
type Error {
field: String!
message: String!
}
type MutationResponse {
success: Boolean!
errors: [Error!]
data: Post
}
`;
GraphQL API の包括的なテストを実装します:
describe('GraphQL API Tests', () => {
it('should fetch user with posts', async () => {
const query = `
query GetUser($id: ID!) {
user(id: $id) {
id
username
posts {
id
title
}
}
}
`;
const variables = { id: 'user123' };
const response = await graphql(schema, query, null, {}, variables);
expect(response.data.user).toBeDefined();
});
});
クエリの複雑さ分析とレート制限を実装します:
const complexityRule = {
Query: {
posts: {
complexity: ({ args, childComplexity }) => {
return (args.limit || 10) * childComplexity;
}
}
}
};
const validateQueryComplexity = (schema, query, variables) => {
const complexity = getQueryComplexity({
schema,
query,
variables,
maximumComplexity: 1000,
complexityRule
});
if (complexity > 1000) {
throw new Error('Query is too complex');
}
};
包括的なモニタリングを実装します:
// Apollo Server monitoring
const server = new ApolloServer({
schema,
plugins: [
ApolloServerPluginUsageReporting({
sendTraces: true,
}),
{
requestDidStart({ request }) {
const startTime = Date.now();
return {
willSendResponse({ response }) {
const duration = Date.now() - startTime;
metrics.recordQueryDuration(duration);
}
};
}
}
]
});
この詳細ガイドに従うことで、サービスの品質とパフォーマンスを維持しながら、RESTからGraphQLへのスムーズな移行を確実にするのに役立ちます。移行の各フェーズを監視し、実際のフィードバックと指標に基づいて戦略を調整することを忘れないでください。