API RESTful para gestão financeira pessoal desenvolvida em Go com foco em segurança, escalabilidade e facilidade de uso. A aplicação permite aos usuários gerenciar suas finanças pessoais, incluindo transações, categorias, metas financeiras, investimentos e relatórios.
- Funcionalidades
- Tecnologias
- Arquitetura
- Requisitos
- Instalação
- Configuração
- Execução
- Documentação da API
- Endpoints
- Autenticação
- Segurança
- Estrutura do Projeto
- Testes
- Contribuição
- Licença
- Registro de novos usuários
- Autenticação via JWT (JSON Web Tokens)
- Validação de propriedade de recursos
- Sistema de planos de usuário com controle de acesso
- Registro de receitas e despesas
- Categorização de transações
- Consulta e filtragem de transações
- Atualização e exclusão de transações
- Criação de categorias personalizadas
- Listagem de categorias
- Atualização e exclusão de categorias
- Criação de metas financeiras
- Acompanhamento de progresso
- Atualização e exclusão de metas
- Registro de investimentos
- Controle de contribuições e saques
- Cálculo de retorno sobre investimentos
- Consulta de histórico de investimentos
- Visão consolidada da situação financeira
- Relatórios e análises financeiras
- Cálculo de score de saúde financeira
- Análise de orçamentos, metas, reserva de emergência e dívidas
- Recomendações personalizadas para melhoria financeira
- Go 1.25+: Linguagem de programação principal
- Gin Framework: Framework web para construção da API REST
- GORM: ORM para interação com banco de dados PostgreSQL
- PostgreSQL: Banco de dados relacional
- golang-jwt/jwt: Geração e validação de tokens JWT
- golang.org/x/crypto: Criptografia bcrypt para senhas
- Swagger/OpenAPI: Documentação interativa da API
- swaggo/swag: Geração automática de documentação Swagger
- oklog/ulid/v2: Geração de identificadores únicos (ULID)
O projeto segue os princípios de Clean Architecture e SOLID, com separação clara de responsabilidades:
-
Domain Layer (
internal/domain/): Contém as entidades de negócio, interfaces de repositórios e serviços, e regras de domínioauth/: Autenticação e autorizaçãouser/: Gestão de usuáriostransaction/: Transações financeirasgoal/: Metas financeirasinvestment/: Investimentosdashboard/: Dashboard e análisesreports/: Relatórios financeiroshealthscore/: Cálculo de saúde financeirabudget/: Orçamentosaccount/: Contas financeirascategory/: Categorias de transaçõescreditcard/: Cartões de créditorecurring/: Transações recorrentes
-
Infrastructure Layer (
internal/infrastructure/): Implementações concretas de repositórios e conexão com banco de dados- Conexão PostgreSQL via GORM
- Implementação de repositórios para todas as entidades
- Migrações automáticas de banco de dados
-
Middleware Layer (
internal/middleware/): Componentes para processamento de requisições HTTP- Autenticação JWT
- Validação de propriedade de recursos
- Validação de planos de usuário
-
Routes Layer (
internal/routes/): Handlers HTTP que conectam as requisições às regras de negócio- Handlers para autenticação
- Handlers para transações
- Handlers para categorias
- Handlers para metas
- Handlers para investimentos
- Handlers para health score
- Handlers para orçamentos
- Handlers para contas
- Handlers para cartões de crédito
- Handlers para transações recorrentes
-
Contracts Layer (
internal/contracts/): DTOs (Data Transfer Objects) e contratos de API -
Utils Layer (
internal/utils/): Utilitários e serviços compartilhados
- Single Responsibility Principle (SRP): Cada camada e componente tem uma responsabilidade única
- Dependency Inversion: Dependências apontam para abstrações (interfaces), não implementações
- Open/Closed Principle: Extensível através de interfaces, fechado para modificação
- DRY (Don't Repeat Yourself): Código reutilizável e modularizado
- KISS (Keep It Simple, Stupid): Soluções simples e diretas
- Docker: Download e instalação
- Docker Compose: Download e instalação
- Git: Para clonar o repositório
- Go 1.25+: Download e instalação
- PostgreSQL 12+: Download e instalação
- Git: Para clonar o repositório
A aplicação não inicia se as credenciais mínimas não estiverem definidas. Configure antes de executar:
DB_HOST=localhost
DB_PORT=5432
DB_USER=<usuario_do_banco>
DB_PASSWORD=<senha_do_banco>
DB_NAME=fynance
DB_SSL_MODE=disable
DB_TIMEZONE=UTC
DB_MAX_OPEN_CONNS=25
DB_MAX_IDLE_CONNS=5
DB_CONN_MAX_LIFETIME=5m
JWT_SECRET_KEY=<chave-com-no-minimo-32-caracteres>
JWT_ISSUER=fynance_api
JWT_EXPIRES_IN=24h
APP_ENV=development
LOG_LEVEL=info
SERVER_PORT=8080
SERVER_READ_TIMEOUT=15s
SERVER_WRITE_TIMEOUT=15s
SERVER_IDLE_TIMEOUT=60sSugestão: crie um arquivo .env (não comite) e carregue com ferramentas como direnv ou dotenvx. Em produção, armazene segredos em um secret manager (AWS Secrets Manager, HashiCorp Vault ou Secret Manager da sua cloud).
A forma mais rápida de executar o projeto é usando Docker e Docker Compose. Esta abordagem não requer instalação manual do Go ou PostgreSQL.
Setup Manual
- Clonar o Repositório
git clone https://github.com/seu-usuario/fynance.git
cd fynance- Configurar Variáveis de Ambiente
Copie o arquivo de exemplo e ajuste as variáveis conforme necessário:
cp .env.example .envIMPORTANTE: Edite o arquivo .env e altere pelo menos:
JWT_SECRET_KEY: Use uma chave forte com mínimo 32 caracteres (gere comopenssl rand -base64 32)DB_PASSWORD: Defina uma senha segura para o banco de dados
- Iniciar os Serviços
docker-compose up -dEste comando irá:
- Criar e iniciar o container do PostgreSQL
- Criar e iniciar o container da API
- Executar as migrações automaticamente
- Expor a API na porta 8080
- Verificar Status dos Containers
docker-compose ps- Acessar a Aplicação
- API: http://localhost:8080/api
- Swagger UI: http://localhost:8080/swagger/index.html
# Ver logs da API
docker-compose logs -f api
# Ver logs do banco de dados
docker-compose logs -f db
# Parar os serviços
docker-compose down
# Parar e remover volumes (dados do banco)
docker-compose down -v
# Rebuild da API após mudanças no código
docker-compose up -d --build api
# Executar comandos dentro do container da API
docker-compose exec api shSe preferir executar localmente sem Docker:
git clone https://github.com/seu-usuario/fynance.git
cd fynancego mod downloadCertifique-se de que o PostgreSQL está instalado e rodando e que as variáveis DB_* apontam para o servidor correto. Não é necessário alterar código; toda a configuração passa por variáveis de ambiente.
CREATE DATABASE fynance;As migrações são executadas automaticamente na inicialização da aplicação.
A carga de configuração ocorre em config/config.go. Recomendações para produção:
- Armazene segredos em secret manager com rotação automatizada
- Ative SSL/TLS para conexões seguras (
DB_SSL_MODE=require) - Ajuste
DB_MAX_OPEN_CONNS,DB_MAX_IDLE_CONNSeDB_CONN_MAX_LIFETIMEconforme a carga - Restringa privilégios do usuário do banco apenas ao schema utilizado
As migrações são executadas automaticamente via GORM AutoMigrate na inicialização da aplicação para as seguintes entidades:
- User
- Goal
- Transaction
- Category
- Investment
- Account
- Budget
- CreditCard
- RecurringTransaction
go run cmd/api/main.gogo build -o bin/api cmd/api/main.go
./bin/apiA documentação Swagger estará disponível em:
http://localhost:8080/swagger/index.html
A API estará disponível em:
http://localhost:8080/api
A documentação completa da API está disponível via Swagger UI:
http://localhost:8080/swagger/index.html
Para regenerar a documentação Swagger após alterações:
swag init -g cmd/api/main.go-
POST
/api/auth/register- Registro de novo usuário- Body:
{ "email": "string", "password": "string", "name": "string" } - Response:
{ "message": "string" }
- Body:
-
POST
/api/auth/login- Autenticação de usuário- Body:
{ "email": "string", "password": "string" } - Response:
{ "token": "string" }
- Body:
- POST
/api/transactions- Criar nova transação - GET
/api/transactions- Listar transações do usuário - GET
/api/transactions/:id - Obter transação específica - PATCH
/api/transactions/:id- Atualizar transação - DELETE
/api/transactions/:id- Excluir transação
- POST
/api/categories- Criar nova categoria - GET
/api/categories- Listar categorias do usuário - PATCH
/api/categories/:id- Atualizar categoria - DELETE
/api/categories/:id- Excluir categoria
- POST
/api/goals- Criar nova meta financeira - GET
/api/goals- Listar metas do usuário - GET
/api/goals/:id- Obter meta específica - PATCH
/api/goals/:id- Atualizar meta - DELETE
/api/goals/:id- Excluir meta
- POST
/api/investments- Criar novo investimento - GET
/api/investments- Listar investimentos do usuário - GET
/api/investments/:id- Obter investimento específico - POST
/api/investments/:id/contribution- Realizar contribuição - POST
/api/investments/:id/withdraw- Realizar saque - GET
/api/investments/:id/return- Obter retorno do investimento - PATCH
/api/investments/:id- Atualizar investimento - DELETE
/api/investments/:id- Excluir investimento
- GET
/api/health-score- Obter score de saúde financeira- Response:
{ "score": number, "status": "string", "label": "string", "color": "string", "budgetHealth": number, "goalsHealth": number, "savingsHealth": number, "recommendations": string[] }
- Response:
- GET
/api/dashboard- Obter dados consolidados do dashboard
Todas as rotas privadas requerem autenticação via JWT. Para acessar essas rotas:
- Faça login via
POST /api/auth/logincom suas credenciais - Receba o token JWT na resposta
- Inclua o token no header
Authorizationde todas as requisições subsequentes:
Authorization: Bearer <seu_token_jwt>
curl -X GET http://localhost:8080/api/transactions \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."Os tokens JWT têm validade de 24 horas. Após expirar, é necessário fazer login novamente.
- Criptografia de Senhas: Senhas são armazenadas com hash bcrypt (cost >= 12)
- JWT com Assinatura: Tokens JWT são assinados e validados
- Validação de Propriedade: Middleware garante que usuários só acessem seus próprios recursos
- Validação de Planos: Sistema de planos permite controle granular de acesso
- Validação de Entrada: Validação de dados de entrada em todos os endpoints
- Tratamento Centralizado de Erros: API responde usando códigos padronizados (
AppError) e logs estruturados - HTTPS Recomendado: Para produção, utilize HTTPS para proteger dados em trânsito
- Nunca exponha credenciais em logs ou mensagens de erro
- Use variáveis de ambiente para configurações sensíveis
- Implemente rate limiting em produção
- Configure CORS adequadamente
- Monitore tentativas de acesso não autorizadas
- Todas as exceções são convertidas em
AppError, com código, mensagem e status HTTP padronizados - Logs estruturados (
zerolog) registram código, rota e causa raiz dos erros - Middlewares retornam mensagens genéricas para evitar vazamento de detalhes sensíveis
- Validações de entrada retornam
VALIDATION_ERRORcom o campo impactado e descrição - Falhas de infraestrutura são encapsuladas como
DATABASE_ERROR, mantendo contexto para observabilidade
Fynance/
├── cmd/
│ └── api/
│ └── main.go # Ponto de entrada da aplicação
├── internal/
│ ├── contracts/ # DTOs e contratos de API
│ │ ├── auth.go
│ │ ├── common.go
│ │ ├── goal.go
│ │ ├── investment.go
│ │ ├── transaction.go
│ │ ├── user.go
│ │ ├── healthscore.go
│ │ ├── budget.go
│ │ ├── account.go
│ │ └── ...
│ ├── domain/ # Camada de domínio (regras de negócio)
│ │ ├── auth/ # Autenticação e autorização
│ │ ├── dashboard/ # Dashboard e análises
│ │ ├── goal/ # Metas financeiras
│ │ ├── investment/ # Investimentos
│ │ ├── reports/ # Relatórios
│ │ ├── transaction/ # Transações
│ │ ├── user/ # Usuários
│ │ ├── healthscore/ # Saúde financeira
│ │ ├── budget/ # Orçamentos
│ │ ├── account/ # Contas
│ │ ├── category/ # Categorias
│ │ ├── creditcard/ # Cartões de crédito
│ │ └── recurring/ # Transações recorrentes
│ ├── infrastructure/ # Camada de infraestrutura
│ │ ├── db.go # Conexão com banco de dados
│ │ ├── goal_repository.go
│ │ ├── investment_repository.go
│ │ ├── transaction_category_repository.go
│ │ ├── transaction_repository.go
│ │ ├── user_repository.go
│ │ ├── budget_repository.go
│ │ ├── account_repository.go
│ │ └── ...
│ ├── middleware/ # Middlewares HTTP
│ │ ├── auth.go # Middleware de autenticação
│ │ ├── jwt.go # Serviço JWT
│ │ ├── jwt_service.go
│ │ ├── plan_validator.go # Validação de planos
│ │ ├── plan_limiter.go # Limites de planos
│ │ ├── rate_limiter.go # Rate limiting
│ │ └── cors.go # CORS
│ ├── routes/ # Handlers HTTP
│ │ ├── authentication.go
│ │ ├── goal.go
│ │ ├── handler.go
│ │ ├── investment.go
│ │ ├── transaction_category.go
│ │ ├── transaction.go
│ │ ├── healthscore.go
│ │ ├── budget.go
│ │ ├── account.go
│ │ └── ...
│ └── pkg/ # Utilitários e pacotes compartilhados
│ ├── pagination.go
│ ├── ulid_utils.go
│ └── query/ # Query builder
├── docs/ # Documentação Swagger
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod # Gerenciamento de dependências
├── go.sum
└── README.md # Este arquivo
go test ./...go test -cover ./...go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.outgo test -bench=. ./...Contribuições são bem-vindas! Para contribuir:
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/AmazingFeature) - Commit suas mudanças (
git commit -m 'Add some AmazingFeature') - Push para a branch (
git push origin feature/AmazingFeature) - Abra um Pull Request
- Siga os princípios SOLID, DRY, KISS
- Mantenha o código limpo e autoexplicativo
- Adicione testes para novas funcionalidades
- Atualize a documentação Swagger quando necessário
- Siga os padrões de código Go (gofmt, go vet)
Este projeto está sob Licença Proprietária - Proibida Monetização.
✅ PERMITIDO - QUALQUER USO:
- ✅ Qualquer uso que NÃO envolva monetização
- ✅ Estudo, aprendizado e pesquisa
- ✅ Incorporação em outros projetos (open source, privado, pessoal, etc.)
- ✅ Criação de obras derivadas
- ✅ Modificação, distribuição e compartilhamento
- ✅ Fork e contribuições para este projeto
- ✅ Uso em projetos pessoais, comerciais (não monetizados), experimentais
- ✅ Uso educacional e acadêmico
- ✅ Copiar código, funções ou módulos para outros projetos
- ✅ Usar padrões arquiteturais em outros projetos
- ✅ Criar aplicações baseadas neste código
- ✅ Uso interno em empresas (desde que não vendido/licenciado)
Resumindo: PODE USAR EM QUALQUER COISA, MENOS PARA MONETIZAR!
❌ ESTRITAMENTE PROIBIDO - APENAS MONETIZAÇÃO:
- ❌ Qualquer forma de monetização ou comercialização
- ❌ Venda do código ou obras derivadas
- ❌ Licenciamento do código por taxa
- ❌ Uso em produtos ou serviços comerciais onde há cobrança
- ❌ Uso em Software-as-a-Service (SaaS) com cobrança
- ❌ Geração de receita através de publicidade relacionada ao código
- ❌ Cobrança de taxas, assinaturas ou qualquer forma de pagamento
- ❌ Qualquer método de obter ganho financeiro do código
Para mais informações sobre os termos de uso, consulte o arquivo LICENSE.
A única restrição é: NÃO MONETIZE!
Você pode usar este código para QUALQUER OUTRO PROPÓSITO:
- ✅ Em outros projetos
- ✅ Para estudo
- ✅ Para criar aplicações
- ✅ Para compartilhar
- ✅ Para qualquer coisa que NÃO envolva ganho financeiro
MAS: Qualquer tentativa de MONETIZAR este código constitui VIOLAÇÃO DE DIREITOS AUTORAIS e pode resultar em AÇÃO JUDICIAL IMEDIATA, incluindo:
- Processo civil por violação de direitos autorais
- Indenização por danos materiais e morais
- Danos estatutários (até $150.000 por obra nos EUA)
- Perdas e danos (incluindo todos os lucros obtidos com uso não autorizado)
- Custas processuais e honorários advocatícios
- Medidas cautelares para cessação imediata do uso não autorizado
Resumindo:
- ✅ Qualquer uso = PERMITIDO (desde que não monetize)
- ❌ Monetização = PROCESSO LEGAL
⚠️
Desenvolvido por Bernardo
Para mais informações, consulte a documentação Swagger em http://localhost:8080/swagger/index.html após iniciar a aplicação.