ࡱ > M O J K L c e] bjbj W QbQbQ V V V V V $ z z z P V z h < < < DF *H H d ih kh kh kh kh kh kh $ j m h V RI E E 0 RI RI h V V < < $ h Q Q Q RI V < V < ih Q RI ih Q Q g h 1h < _6B L p g Uh h 0 h g Vn xO Vn 1h Vn V 1h $ RI RI Q RI RI RI RI RI h h Q RI RI RI h RI RI RI RI Vn RI RI RI RI RI RI RI RI RI L : Ministrio da Sade
Secretaria Executiva
Departamento de Informtica do SUS
Coordenao-Geral de Anlise e Manuteno
METODOLOGIA DE DESENVOLVIMENTO DE SOFTWARE
Arquitetura de Referncia Web Back-end
Instrues de preenchimento do documento Este documento dever seguir as seguintes consideraes de preenchimento:
Fonte: Arial o Tamanho: 10 o Cor: Preta
Sigla e nome do Projeto: Caixa Alta
[ ... ]: Retirar os colchetes ao transcrever o texto
Quando algum item no for aplicado a este documento informar a sigla N/A
[SIGLA] [NOME DO PROJETO] Gestor do Projeto Klaymer Paz klaymer.paz@saude.gov.br 3315-2212
Histrico de Reviso Data Verso N Ordem de
Descrio
Servio Autor 26/12/2018 1.0 04.2018 Criao do documento Eduardo Nascimento
Sumrio
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc17796" \h Sumrio PAGEREF _Toc17796 \h2
HYPERLINK \l "_Toc17797" \h 1. INTRODUO PAGEREF _Toc17797 \h3
HYPERLINK \l "_Toc17798" \h 2. VISO DE IMPLANTAO PAGEREF _Toc17798 \h3
HYPERLINK \l "_Toc17799" \h 2.1 Viso de Implementao - Back-end PAGEREF _Toc17799 \h3
HYPERLINK \l "_Toc17800" \h 2.2 Componentes de Referncia Arquitetura Java PAGEREF _Toc17800 \h4
HYPERLINK \l "_Toc17801" \h 2.2.1 Spring Boot 2 PAGEREF _Toc17801 \h4
HYPERLINK \l "_Toc17802" \h 2.2.2 WebService RESTFUL PAGEREF _Toc17802 \h5
HYPERLINK \l "_Toc17803" \h 2.2.3 Entidades PAGEREF _Toc17803 \h5
HYPERLINK \l "_Toc17804" \h 2.2.4 Repositrios PAGEREF _Toc17804 \h6
HYPERLINK \l "_Toc17805" \h 2.2.5 Excees PAGEREF _Toc17805 \h7
HYPERLINK \l "_Toc17806" \h 2.2.6 Mapper PAGEREF _Toc17806 \h7
HYPERLINK \l "_Toc17807" \h 2.2.7 Controle Transacional PAGEREF _Toc17807 \h8
HYPERLINK \l "_Toc17808" \h 2.2.8 Processamento em lote PAGEREF _Toc17808 \h9
HYPERLINK \l "_Toc17809" \h 2.2.9 Autorizao/Autenticao PAGEREF _Toc17809 \h9
HYPERLINK \l "_Toc17810" \h 2.2.10 Paginao PAGEREF _Toc17810 \h10
HYPERLINK \l "_Toc17811" \h 2.2.11 Envio de email PAGEREF _Toc17811 \h10
HYPERLINK \l "_Toc17812" \h 2.2.12 Relatrios PAGEREF _Toc17812 \h10
HYPERLINK \l "_Toc17813" \h 2.2.13 Teste unitrio PAGEREF _Toc17813 \h10
HYPERLINK \l "_Toc17814" \h 2.2.14 Logs PAGEREF _Toc17814 \h11
HYPERLINK \l "_Toc17815" \h 2.2.15 Trilhas de Auditoria PAGEREF _Toc17815 \h11
HYPERLINK \l "_Toc17816" \h 2.2.16 Estrutura do Projeto PAGEREF _Toc17816 \h11
HYPERLINK \l "_Toc17817" \h 2.2.17 Gerncia de dependncias PAGEREF _Toc17817 \h12
HYPERLINK \l "_Toc17818" \h 2.2.18 API PAGEREF _Toc17818 \h12
HYPERLINK \l "_Toc17819" \h 3. REFERNCIAS PAGEREF _Toc17819 \h13
INTRODUO
A proposta deste documento unir a arquitetura bsica e os conceitos fundamentais dos sistemas desenvolvidos pelo DATASUS. Estes padres e diretrizes so apresentados em forma de vises arquiteturais que visam cobrir os principais aspectos tcnicos relativos a estrutura e ao desenvolvimento dos sistemas. Segundo Buschman et ali. (1996), um padro arquitetural expressa um esquema de organizao estrutural fundamental para sistemas de software, fornece um conjunto de subsistemas prevenidos, especifica suas responsabilidades e inclui regras e diretrizes para organizar as relaes entre eles.
A Arquitetura de Referncia gera um aumento na eficincia na Entrega de Projetos de Novas solues tecnolgicas, pois:
A Arquitetura de Referncia em um contexto de T.I. Integradora um mapa que garante as entregas de projetos de T.I. de maneira coordenada e aderente estratgia corporativa.
A Arquitetura de Referncia , alm de um mapa, um manual de como configurar cada componente que ser integrado em uma nova soluo tecnolgica, desta maneira a quantidade de retrabalho e o tempo de execuo na reconfigurao de componentes sero consideravelmente reduzidos e isso causa um aumento da eficincia nas entregas de Projetos de TI.
O documento necessita de revises peridicas. Normalmente, novas necessidades de negcios motivam revises na Arquitetura de Referncia para que ela possa atender essas novas necessidades. O Grau de alinhamento desta Arquitetura com a estratgia da empresa pode fornecer um caminho de duas vias, ou seja, inovaes tecnolgicas podem gerar novas capacidades ao modelo de negcios da empresa.
VISO DE IMPLANTAO
Viso de Implementao - Back-end
A implementao de uma aplicao Java no DATASUS deve ser feita utilizando o framework de desenvolvimento JAVA do DATASUS (REST e CORE), desenvolvido na plataforma JEE 8.
Componente Descrio Forma de Licenciamento Spring Framework que agrega funcionalidades para as camadas de apresentao, negcios e persistncia, oferecendo uma arquitetura bem Reutilizao resolvida com reutilizao de conceitos com injeo de dependncia e inverso de controle reduzindo o acoplamento entre as camadas. Spring Data JPA Framework para implementao de repositrios baseados em JPA. Reutilizao Spring Security Framework de autenticao e controle de acesso. Reutilizao Spring Boot 2 Framework de configurao e publicao de aplicao. Reutilizao Jasper Reports Framework para gerao de relatrios com foco principal no formato PDF. Reutilizao Hibernate Framework ORM utilizado na camada de persistncia. Reutilizao DATASUS Spring Core Framework interno com a implementao dos componentes bsicos de negcio e persistncia baseados no framework Spring. Desenvolvimento Interno DATASUS REST
Spring Framework interno com a implementao camada Webservice RESTful utilizando o framework Spring. Desenvolvimento Interno
Componentes de Referncia Arquitetura Java
Spring Boot 2
O Spring Boot em sua primeira verso foi muito conhecida pela facilidade de criao, configurao de projetos e utilizao de micro servios. Na verso 2 tiveram algumas quebras de compatibilidades e incluso de novas funcionalidades que ajudam muito o desenvolvimento e melhoria da qualidade do cdigo.
A verso mnima do java necessrio a 8, pois so utilizados mtodos e tipos que apenas so encontradas a partir dessa verso, porm a verso que recomendada para ser usada a verso 9.
Para adicionar spring boot 2 ao projeto, utilizar o comando:
$ spring init nome-projeto -dweb
Ao rodar esse comando ser gerado um projeto com Spring Boot 2.0.
ou incluir no pom.xml:
org.springframework.boot
spring-boot-starter-parent
2.0.6.RELEASE
WebService RESTFUL
A camada de apresentao composta do WebService RESTful ser implementada utilizando o framework Spring MVC em conjunto com o framework DATASUS REST WEB contendo as implementaes dos objetos DTO de resposta, rotinas de tratamento de excees, com configuraes de converso entre objetos Java e JSON e outros recursos.
Na utilizao deste framework, ser criada uma classe Controller com a anotao @RestController, desta forma o componente ir expor os mtodos desejados em recursos REST.
@Api(value = Sistema controller)
@RequestMapping(value = /exemplo)
@RestController public class ExemploController {
@Autowired private SistemaService sistemaService;
@ApiOperation(value = Obter um sistema)
@GetMapping(value = /{id}, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity obter(@PathVariable(id) Long id) { return
ResponseEntity.ok(sistemaService.obter(id));
}
Entidades
Entidades so objetos que possuem uma identidade de negcios distinta que separada dos valores de seus atributos. Duas entidades so diferentes mesmo se os valores de seus atributos forem os mesmos e no podem ser utilizadas intercambiavelmente.
Identificar entidades importante porque elas correspondem a conceitos do mundo real que so centrais para o modelo de domnio do sistema.
@Entity
@Table(name = "TB_SISTEMA", schema = "DBSCPA")
@NamedQuery(name = "Sistema.buscarSistemasPorUsuario", query = "SELECT * FROM
PerfilUsuario pu WHERE pu.usuario.id =:idUsuario") public class Sistema {
@Id
@Column(name = "CO_SEQ_SISTEMA") private Long id;
@OneToMany(mappedBy = "sistema", fetch = FetchType.LAZY) private List perfis;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "CO_UNIDADE_DATASUS", updatable = false, insertable = false) private UnidadeOrganizacional unidadeDataSus;
}
Repositrios
Repositrios gerenciam colees de entidades e definem mtodos para encontrar e remover entidades. Um repositrio encapsula o framework de persistncia e constitudo por uma interface e uma classe de implementao. A interface deve ter os mtodos que podem ser chamados pelo cliente do repositrio, e a classe de implementao implementa a interface chamando o framework de persistncia.
A implementao referncia de repositrios baseados em banco de dados no ambiente Java baseada no framework Spring Data. Este projeto tem como proposta de unificar e facilitar o acesso a diferentes tecnologias de armazenamento de dados, como bancos de dados relacionais e os NoSQL.
O Spring Data disponibiliza uma estrutura para criao de repositrios. Ser utilizado na arquitetura o subprojeto Spring Data JPA. A soluo de repositrio do framework disponibiliza as operaes bsicas de CRUD. E ainda oferta um mecanismo para a criao de consultas com uma quantidade menor de cdigo, dispensando na maioria das situaes a criao de uma classe de implementao do repositrio.
package br.gov.datasus.scpa.repository; public interface FuncionalidadeRepository extends CrudRepository { public Page buscarFuncionalidadePorSistema(@Param("idSistema") Long
idSistema, Pageable page); public List buscarFuncionalidadePorSistema(@Param("idSistema") Long idSistema);
}
Excees
As regras para o tratamento de excees:
A aplicao possui um mdulo para tratamento de excees. Dessa forma a toda exceo deve ser enviada e tratada por este mdulo.
Mapper
O uso de mapper para o projeto busca facilitar o mapeamento de objeto para objeto. O uso do Mapper simples, bastando instanci-lo para em seguida chamar seu mtodo map(..) que popula o DTO e recebe o objeto fonte e o tipo do DTO.
Com o framework do DATASUS, a implementao seria:
package br.gov.datasus.scpa.model.mapper;
@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE) public interface UsuarioBasicoMapper extends BaseMapper {
UsuarioBasicoDTO toDto(Usuario entity);
Usuario toEntity(UsuarioBasicoDTO dto);
List toDto(List entities);
List toEntity(List dtos);
List toDto(Iterable entities);
}
importante mencionar que um Object-to-Object Mapper no s serve para mapear o domnio para um DTO. H vrias outras motivaes para uma hierarquia paralela. De qualquer forma um objectto-object mapper assume essa parte trabalhosa de copiar os valores entre objetos.
Controle Transacional
A JTA (Java Transaction API) ser empregada em conjunto com os recursos do Spring Framework. Sua configurao ser feita no arquivo de contexto do Spring. Caso a aplicao utilize mais de um recurso (exemplo datasource e JMS) em uma mesma transao, ambos devero implementar a interface javax.transaction.xa.XAResource.
A demarcao de transaes dever ser feita sempre nos Services Facades com o uso da anotao @Transactional.
Ateno especial deve ser dada na configurao da transao em funo de excees. Exceptions que estendam RuntimeException provocam automaticamente a realizao de rollback em uma transao. Checked exceptions no. Para provocar o rollback as checked exceptions devem ser informadas na propriedade roll-backForClassname da anotao @Transactional.
package br.gov.datasus.scpa.service;
@Service
@Transactional(value = TxType.SUPPORTS) public class UsuarioService {
@Autowired private UsuarioRepository usuarioRepository;
@Autowired private UsuarioBasicoMapper usuarioBasicoMapper; public PageResponse buscarUsuariosPorSistema(Long idSistema, Pageable paginacao) { Page page = usuarioRepository.buscarUsuariosPorSistema(idSistema, paginacao); return PaginationHelper.toPageResponse(page, usuarioBasicoMapper.toDto(page.getContent()));
}
...
}
Processamento em lote
O termo lote ou batch bastante comum para programadores de Mainframe. As aplicaes batch podem ser consideradas como programas ou rotinas executadas em segundo plano que possuem um fluxo a percorrer e sem a interveno direta do usurio.
Para a construo de processamento batch ser utilizado o framework Spring Batch. Os Job's correspondentes aos processamentos sero embutidos em uma aplicao web isolados da aplicao principal.
O Spring Batch utiliza uma estrutura chamada de JobRepository para o armazenamento de metadados referentes aos Jobs. Os metadados podem ser armazenados apenas em memria RAM ou em banco de dados.
Durante as atividades de desenvolvimento dever ser utilizado o armazenamento em memria RAM. Em ambientes de teste (desenvolvimento/homologao) e produo dever ser utilizado o armazenamento em banco de dados.
Autorizao/Autenticao
O Sistema de Cadastro e Permisso de Acesso (SCPA) foi desenvolvido pelo Ministrio da Sade no Departamento de Informtica do SUS (DATASUS), com o intuito de unificar o cadastramento dos usurios aos sistemas WEB do Ministrio da Sade.
O SCPA disponibiliza um conjunto de webservices que sero consumidos para:
Autenticao do usurio
Recuperao de perfis de um usurio
Recuperao das permisses de um perfil
O framework Spring Security ser utilizado nas operaes de autenticao e autorizao. O framework do DATASUS REST SPRING possui uma implementao padro com os componentes de autenticao e autorizao na camada WebService RESTful baseada no SCPA.
Paginao
Ser utilizada a tcnica de paginao sob demanda com o uso dos recursos de banco de dados e do Spring Data JPA. Basicamente, os repositrios devero disponibilizar mtodos que retornem uma instncia de Page e recebam em seus parmetros um objeto do tipo Pageable. O Spring Data JPA calcular automaticamente a quantidade total de objetos.
Todas as respostas devem ser paginadas, salvo situaes de exceo.
Envio de email
Utilizar os recursos disponibilizados pelo Spring Framework. A gerao do texto do e-mail dever ser feita com o uso de templates feitos com o Velocity.
Relatrios
Os relatrios sero produzidos com o uso do framework Jasperreports. A gerao ser feita por classes de servios. Para evitar problemas como o consumo elevado do heap space durante a etapa de Preenchimento (Fill Phase) em grandes relatrios deve ser usado o recurso de virtualizao do Jasperreports.
A definio do tipo de virtualizador a ser utilizado responsabilidade do arquiteto do sistema. O consumo de recursos para relatrios com sada diferente de PDF dever ser analisado com cuidado pelo arquiteto do sistema, pois algumas apis de exportao (ex: JexcelAPI) exigem que todo o contedo esteja em memria.
Ser utilizada como linguagem de consulta a EJBQL. Para evitar problemas de consumo de memria, dever ser utilizado o recurso de paginao. O nmero de objetos por pginas (jpa) ser definido com preenchimento da propriedade \net.sf.jasperreports.ejbql.query.page.size".
Teste unitrio
Um teste unitrio deve ser capaz de examinar o comportamento do cdigo sob as mais variadas condies, ou seja, como o cdigo deve se comportar se determinado parmetro for passado (ou no), o que ele retorna (se determinada condio for verdadeira), os efeitos colaterais que ele causa durante a sua execuo, se determinada exceo lanada, etc.
Os frameworks Junit e Mockito constituiro a estrutura bsica para os testes unitrios nos sistemas.
Logs
Ser utilizado o framework Log4j para o registro de logs gerados pelo sistema.
Appenders indicados para uso:
FileAppender: Os responsveis pela administrao de servidores de aplicao redirecionam as informaes enviadas para o console para arquivos, com uma rotina de compactao e rodzio automtico.
SMTPAppender: Utilizado para enviar as informaes geradas pelo log para um endereo de e- mail que ser acessado pela equipe responsvel pela manuteno/evoluo do sistema.
Trilhas de Auditoria
As trilhas de auditoria sero registradas automaticamente em tabelas previamente definidas com a equipe de administrao de dados. Ser necessrio informar a sesso do banco de dados, as informaes que sero registrados na trilha de auditoria.
O framework DATASUS j possui uma implementao que executa os procedimentos de recuperao dos dados de usurio e o IP do computador que executou a operao e atribuio a sesso do banco de dados. Para utilizar essa funcionalidade obrigatrio que o repositrio extenda a classe que contm a implementao do registro de trilhas de auditoria.
Estrutura do Projeto
A estrutura de um projeto Java ser composta de um projeto principal que ir conter um conjunto de projetos separados pela camada lgica/fsica ou caracterstica de implantao.
O padro de estrutura de projetos ser composto de um projeto principal que ir conter um conjunto de projetos na estrutura definida pelo archetype.
-Principal
--{Projeto Core {projeto contendo as entidades, camadas de negcio e persistncia.
--{Projeto Web {projeto contendo a camada REST da aplicao
--{Projeto Ear {projeto utilizado para empacotar os projetos para a implantao
Outros projetos podem existir nessa estrutura como, por exemplo, um subprojeto com artefatos para processamento em lote que podem ser implantados em uma estrutura diferente do projeto web.
Gerncia de dependncias
Os projetos devero ser construdos utilizando o Maven (conforme guia de desenvolvimento) para a gerncia de dependncias. Alm de permitir um melhor controle dos artefatos e dependncias de um projeto, o Maven permite que a construo do projeto seja feita de forma automatizada pela equipe de gesto de configurao.
Cada projeto e subprojetos dever possuir um arquivo pom.xml na raiz do diretrio raiz com as configuraes do projeto e suas dependncias.
O DATASUS disponibiliza os artefatos Maven atravs do repositrio Nexus.
Este repositrio localizado na URL:
http://repo1-maven.saude.gov.br/nexus/.
Para auxiliar e padronizar os projetos desenvolvidos no DATASUS, na criao dos templates iniciais dos projetos, sero utilizados arqutipos (archetypes) do Maven.
O archetype ser atualizado de acordo com a arquitetura de referncia e suas diretrizes.
API
importante que quem consuma a API saiba do que se trata e quais os contratos que so firmados no envio e no recebimento de dados. O Swagger uma das ferramentas mais importantes que visa solucionar esse problema de documentao e outros.
Para a documentao dos cdigos necessrio o mnimo de declaraes, sendo elas:
@Api(value = "Sistema controller")
@RequestMapping(value = "/exemplo")
@RestController public class ExemploController { @Autowired private SistemaService sistemaService
@ApiOperation(value = "Obter um sistema")
@GetMapping(value = "/{id}", produces = MediaType.APPLICATION_JSON_VALUE) public ResponseEntity obter(@PathVariable("id") Long id) { return
ResponseEntity.ok(sistemaService.obter(id));
}
A primeira anotao do Swagger que utilizamos a @Api, onde no nosso exemplo declaramos do que se trata nossa API. Veja que ela utilizada uma vez no Controller.
A outra anotao utilizada a @ApiOperation, para cada endpoint, declarando do que se trata a operao.
Ao fazer a build e rodar a aplicao, o processo ir disponibilizar o Swagger na URL http://localhost:8080/swagger-ui.html (a porta padro 8080, mas no seu projeto pode ter sido configurada para outra porta, verifique no log ao inicializar).
REFERNCIAS
Patterns of Enterprise Application Architecture, Martin Fowler et al., http://www.martinfowler.com
Repository, JavaBuilding, URL: http://www.javabuilding.com/academy/patterns/repository.html
REST API Design RuleBook, Mark Masse, HYPERLINK "http://shop.oreilly.com/product/0636920021575.do" \h http://shop.oreilly.com/product/0636920021575.do HYPERLINK "http://shop.oreilly.com/product/0636920021575.do" \h
OWASP Top 10 { 2013 - https://www.owasp.org/images/9/9c/OWASPT op102013P TBR:pdf
Arquitetura de Referncia WEB Back-end
Arquitetura de Referncia WEB Back-end
Metodologia de Desenvolvimento de Software Verso 1.0 Pg. PAGE \* MERGEFORMAT 2 de NUMPAGES \* MERGEFORMAT 13
Metodologia de Desenvolvimento de Software Verso 1.0 Pg. PAGE \* MERGEFORMAT 2 de NUMPAGES \* MERGEFORMAT 13
Arquitetura de Referncia WEB Back-end
Arquitetura de Referncia WEB Back-end
Metodologia de Desenvolvimento de Software Verso 1.0 Pg. PAGE \* MERGEFORMAT 10 de NUMPAGES \* MERGEFORMAT 13
Metodologia de Desenvolvimento de Software Verso 1.0 Pg. PAGE \* MERGEFORMAT 13 de NUMPAGES \* MERGEFORMAT 13
Arquitetura de Referncia WEB Back-end
Metodologia de Desenvolvimento de Software Verso 1.0 Pg. PAGE \* MERGEFORMAT 10 de NUMPAGES \* MERGEFORMAT 13
* + N O | } ~ N O w x y z
)
2
J
K
]
`
h8 h\g >*CJ wh #h8 h\g 5CJ OJ PJ QJ ^J h8 h\g 5CJ h8 h\g CJ h8 h CJ h8 h\g 6CJ h8 h\g 5B*CJ ph
h\g CJ$ h\g OJ PJ QJ ^J h\g
h\g CJ h h\g 5 4 + O ~ c M $ ) d ])^ ` a$ 0 $ C $d %d &d 'd N O P Q ] ^a$ : $
Z $d %d &d 'd N O P Q ] ^` a$ 0 $ $d %d &d 'd N O P Q ] ^a$ O y z c I $ $If ] ^ ` a$ gd8 [ kd $$If r! $ `
t
$6 4 K 4 4 4 s ap
yt8 $S $If ]S^ ` a$gd8 $ ]^ ` a$ $ ] ^` a$
K
[ H $ ] ^ ` a$ R kd $$If r!$
t $6 4 K 4 4 4 s ap
yt8 $
&