Archivo de apoyo de la skill bun-hono-api · rules.md
El texto de las convenciones está escrito en portugués y se muestra aquí tal como está en el repositorio.
Rules — O que é PROIBIDO
Estas regras existem para manter a arquitetura consistente. Violações devem ser corrigidas em code review.
❌ 1. Lógica de negócio fora do Service
A lógica de negócio vive exclusivamente no Service. Nunca em repositories ou routes.
// ❌ errado — lógica no repository
class PostRepository {
async create(data: NewPost) {
if (data.title.length < 3) throw new Error('Title too short'); // ← PROIBIDO
return db.insert(posts).values(data);
}
}
// ❌ errado — lógica na route
postsRouter.post('/', async (c) => {
const body = c.req.valid('json');
if (body.title.length < 3) throw new BadRequestError('Title too short'); // ← PROIBIDO
// ...
});
// ✅ correto — lógica no service
class CreatePostService {
async execute(input: CreatePostInput) {
if (input.title.length < 3) throw new BadRequestError('Title too short');
return this.postRepository.create(input);
}
}
❌ 2. Service com mais de uma responsabilidade
Cada service faz exatamente uma coisa e expõe apenas execute().
// ❌ errado — service faz criar E notificar E atualizar contador
class PostService {
async createPost() { ... }
async notifyFollowers() { ... }
async updatePostCount() { ... }
}
// ✅ correto — um service, uma operação
class CreatePostService {
async execute(input: CreatePostInput): Promise<Post> { ... }
}
❌ 3. Entrada HTTP sem validação Zod
Toda rota que recebe dados (body, query, param) deve usar zValidator do Hono.
// ❌ errado — sem validação
postsRouter.post('/', async (c) => {
const body = await c.req.json(); // ← sem validação, sem tipo
// ...
});
// ✅ correto — com zValidator
postsRouter.post('/', zValidator('json', createPostSchema), async (c) => {
const body = c.req.valid('json'); // ← tipado e validado
// ...
});
❌ 4. Erros genéricos — sempre use typed AppError
Nunca lance new Error('mensagem'). Use sempre os typed errors de src/modules/shared/errors.
// ❌ errado
throw new Error('Post not found');
throw new Error('User already exists');
// ✅ correto
import { NotFoundError, ConflictError } from '@/modules/shared/errors';
throw new NotFoundError('Post not found');
throw new ConflictError('User already exists');
Errors disponíveis: NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, BadRequestError.
❌ 5. Interface de model redundante quando o tipo do Drizzle já serve
Não crie interfaces TypeScript que espelham 1:1 um schema Drizzle. Use os tipos inferidos exportados pelo próprio schema.
// ❌ errado — interface redundante que duplica o schema
export interface Post {
id: string;
title: string;
userId: string;
createdAt: Date;
updatedAt: Date;
}
// ✅ correto — tipo inferido no arquivo de schema
export type Post = typeof posts.$inferSelect;
export type NewPost = typeof posts.$inferInsert;
Crie interfaces em models/ apenas para tipos compostos que não correspondem a uma única tabela (ex: resultado de join com objetos aninhados).
❌ 6. Mapper desnecessário em queries simples
Não escreva mapper para queries que retornam diretamente o tipo $inferSelect. O Drizzle já mapeia snake_case → camelCase automaticamente via o nome da propriedade no schema.
// ❌ errado — mapper desnecessário para query simples
function toPost(row: Post): Post {
return {
id: row.id,
title: row.title,
userId: row.userId,
createdAt: row.createdAt,
updatedAt: row.updatedAt,
};
}
async findById(id: string): Promise<Post | null> {
const [row] = await db.select().from(posts).where(eq(posts.id, id));
return row ? toPost(row) : null; // ← mapper inútil aqui
}
// ✅ correto — sem mapper
async findById(id: string): Promise<Post | null> {
const [row] = await db.select().from(posts).where(eq(posts.id, id));
return row ?? null;
}
Mapper é necessário apenas quando a query faz join e o resultado é um tipo composto diferente do schema.
❌ 7. Coluna do banco sem snake_case explícito
O Drizzle não converte automaticamente. Sempre declare o nome da coluna explicitamente em snake_case.
// ❌ errado — Drizzle vai criar coluna "userId" no banco
userId: uuid('userId').notNull(),
// ✅ correto — coluna no banco será "user_id"
userId: uuid('user_id').notNull(),
❌ 8. Imports com caminhos relativos profundos
Use sempre o path alias @/*. Proibido usar ../../ para sair do módulo atual.
// ❌ errado
import { db } from '../../../infra/database/drizzle';
// ✅ correto
import { db } from '@/infra/database/drizzle';
❌ 9. Refresh token armazenado no banco
O refresh token é um JWT — não é armazenado em banco de dados. Toda validação usa assinatura criptográfica.
// ❌ errado — salvar refresh token no banco
await db.insert(refreshTokens).values({ token, userId });
// ✅ correto — gerar JWT com JwtService
const refreshToken = await jwtService.signRefreshToken(userId);